Quick Start
Installation
uv add circus-mcp
Basic Usage

Start the daemon

uv run circus-mcp start-daemon

Add and start a web application

uv run circus-mcp add webapp "python app.py" uv run circus-mcp start webapp

Check what's running

uv run circus-mcp overview

View logs

uv run circus-mcp logs webapp That's it! Your process is now managed by Circus MCP.

Key Features
🚀 Process Management Made Easy

Add processes with options

uv run circus-mcp add api "uvicorn app:api" --numprocesses 4 --working-dir /app

Smart operations (won't fail if already running)

uv run circus-mcp ensure-started api

Bulk operations

uv run circus-mcp start-all uv run circus-mcp restart-all 📊 Comprehensive Monitoring

Beautiful overview of all services

uv run circus-mcp overview

Detailed status information

uv run circus-mcp status-all

Real-time log viewing

uv run circus-mcp tail api uv run circus-mcp logs-all 🤖 AI Agent Integration Circus MCP includes built-in MCP protocol support, allowing AI agents to manage your processes:

Start MCP server for AI integration

uv run circus-mcp mcp Configure in your AI agent using the recommended stdio transport:

{
"mcpServers": {
"circus-mcp": {
"command": "uv",
"args": ["run", "circus-mcp", "mcp"]
}
}
}
Note: This tool is designed for local development environments using MCP's stdio transport method as specified in the MCP documentation. This approach provides secure, direct communication between AI agents and the process manager.

Common Use Cases
Web Application Management

Production web app with multiple workers

uv run circus-mcp add webapp "gunicorn app:application" --numprocesses 4
uv run circus-mcp add worker "celery worker -A app" --numprocesses 2
uv run circus-mcp ensure-started all
Development Environment

Start your development stack

uv run circus-mcp add frontend "npm run dev" --working-dir /app/frontend
uv run circus-mcp add backend "python manage.py runserver" --working-dir /app/backend
uv run circus-mcp add redis "redis-server"
uv run circus-mcp start-all
Microservices

Manage multiple services

uv run circus-mcp add auth-service "python auth_service.py"
uv run circus-mcp add user-service "python user_service.py"
uv run circus-mcp add notification-service "python notification_service.py"
uv run circus-mcp ensure-started all
Why Circus MCP?
vs. Docker Compose
Lighter: No containers needed, just process management
Faster: Direct process execution, no container overhead
Simpler: One command to rule them all
vs. systemd
User-friendly: Simple commands instead of unit files
Cross-platform: Works on any system with Python
AI-ready: Built-in MCP support for automation
vs. PM2
Python-native: Perfect for Python applications
AI integration: MCP protocol support out of the box
Comprehensive: Process + log management in one tool
Advanced Features
Intelligent State Management

These commands are safe to run multiple times

uv run circus-mcp ensure-started webapp # Only starts if not running
uv run circus-mcp ensure-stopped worker # Only stops if running
Bulk Operations

Work with all processes at once

uv run circus-mcp start-all # Start everything
uv run circus-mcp stop-all # Stop everything
uv run circus-mcp restart-all # Restart everything
uv run circus-mcp logs-all # See all logs
Log Management

View logs with filtering

uv run circus-mcp logs webapp --lines 100 --stream stderr
uv run circus-mcp tail webapp --stream stdout

See recent activity across all services

uv run circus-mcp logs-all Installation & Setup System Requirements Python 3.10 or higher Any operating system (Linux, macOS, Windows) Installation Options

From PyPI (recommended)

uv add circus-mcp

With pip (alternative)

pip install circus-mcp

From source

git clone https://github.com/aether-platform/circus-mcp.git cd circus-mcp uv sync Verify Installation uv run circus-mcp --help uv run circus-mcp daemon-status Configuration Circus MCP works out of the box with sensible defaults. For advanced usage:

Custom Circus Configuration

Use your own circus.ini

uv run circus-mcp start-daemon -c /path/to/your/circus.ini
Process Configuration

Add processes with full configuration

uv run circus-mcp add myapp "python app.py" \
--numprocesses 4 \
--working-dir /app \
Getting Help
Documentation
Development Guide - For contributors and advanced usage
API Reference - Complete command and API documentation
Support
GitHub Issues: Report bugs or request features
Discussions: Join the community
Releases: Latest releases and changelogs
Quick Command Reference

Daemon

uv run circus-mcp start-daemon
uv run circus-mcp stop-daemon
uv run circus-mcp daemon-status

Process Management

uv run circus-mcp add <name> <command> uv run circus-mcp start/stop/restart <name> uv run circus-mcp ensure-started/ensure-stopped <name>

Monitoring

uv run circus-mcp overview uv run circus-mcp status-all uv run circus-mcp logs <name>

AI Integration

uv run circus-mcp mcp Examples Repository Check out our examples repository for real-world usage patterns:

Django + Celery setup
FastAPI microservices
React + Node.js development stack
Machine learning pipeline management
License
MIT License - see LICENSE for details.

About the Author
AetherPlatform - Building the future of cloud-native development tools

GitHub: @aether-platform
Project Website: AetherPlatform
Contact: aether-platform@re-x.info
Our Mission
We develop tools that enhance developer productivity through AI integration and modern cloud-native technologies. CircusMCP is part of our broader ecosystem of development tools designed to streamline the software development lifecycle.

Acknowledgments
We extend our heartfelt gratitude to the Circus development team for creating such a robust and reliable process management foundation. Their excellent work made this project possible. Circus MCP builds upon their solid architecture to bring modern AI agent integration to process management.

Related Projects
Circus - The underlying process manager (Thank you to the Circus team!)
Model Context Protocol - AI agent communication standard
AetherPlatform - Cloud-native development tools
Made with ❤️ by AetherPlatform

Circus MCP: Simple process management, powerful automation.