Circus MCP

A simple and powerful process management tool that combines Circus process manager with AI agent integration through the Model Context Protocol (MCP).

What is Circus MCP?

In today's complex microservices development landscape, Circus MCP enables AI coding agents to work more efficiently, contributing to society through better development productivity.

Circus MCP provides direct process control through the Model Context Protocol, eliminating the overhead of shell commands and reducing token consumption for AI agents managing development environments.

Core Features:

• AI Integration: Built-in MCP protocol support for coding agents
• Simple Commands: Easy-to-use CLI for developers
• Smart Operations: Idempotent commands that work reliably
• Microservices Ready: Manage multiple services effortlessly

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.

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.