circus-mcp by aether-platform - MCP Server

Circus MCP

Simplify development server management and log reading for AI coding agents.

Circus MCP provides coding agents with streamlined access to development server startup and log monitoring through the Model Context Protocol (MCP). By offering direct process management capabilities, it eliminates the complexity of shell command parsing and reduces token consumption for AI agents working in development environments.

MCP Integration Sequence

sequenceDiagram
    participant Agent as AI Coding Agent
    participant MCP as Circus MCP Server
    participant Circus as Circus Daemon
    participant Process as Development Server

    Agent->>MCP: Request: add_process("webapp", "npm run dev")
    MCP->>Circus: Add watcher configuration
    Circus-->>MCP: Process added successfully
    MCP-->>Agent: {"status": "ok", "message": "Process added"}

    Agent->>MCP: Request: start_process("webapp")
    MCP->>Circus: Start watcher
    Circus->>Process: Launch npm run dev
    Process-->>Circus: Process started (PID: 1234)
    Circus-->>MCP: Process status: active
    MCP-->>Agent: {"status": "ok", "process": "webapp"}

    Agent->>MCP: Request: get_logs("webapp", lines=50)
    MCP->>Circus: Fetch stdout/stderr logs
    Circus-->>MCP: Log entries
    MCP-->>Agent: {"status": "ok", "logs": ["Server started on port 3000..."]}

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

- For contributors and advanced usage
- 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 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.