Claude Code Multi-Process MCP Server

# Claude Code Multi-Process MCP Server A FastMCP-based multi-process execution server for Claude Code that provides asynchronous task processing capabilities. ## Features - ✅ **Asynchronous Execution** - Start background tasks and continue working immediately - ✅ **Multi-Instance Parallelism** - Run multiple Claude Code sessions simultaneously - ✅ **Automatic Cleanup** - Prevent zombie processes with automatic resource reclamation - ✅ **Process Monitoring** - Real-time task status and process information tracking - ✅ **Task Management** - Complete task lifecycle management ## Quick Start ### 1. Install Dependencies ⚠️ **Important**: Due to macOS externally-managed-environment restrictions, you must use a virtual environment. ```bash # Clone and navigate to project cd <project-path> # Create virtual environment python3 -m venv venv # Activate virtual environment and install dependencies source venv/bin/activate pip install -r requirements.txt # Deactivate when done (optional) deactivate ``` ### 2. Configure Claude Code Add to your `~/.claude/settings.json`: ```json { "mcpServers": { "cc-multi-process": { "command": "/absolute/path/to/project/venv/bin/python3", "args": ["/absolute/path/to/project/main.py"], "description": "Claude Code Multi-Process MCP Server - Provides parallel task execution capabilities" } } } ``` > **Critical Notes**: > - Use **virtual environment Python** path: `/your/project/path/venv/bin/python3` > - Use **absolute paths** for both command and args > - Replace `/absolute/path/to/project` with your actual project path > - The virtual environment must contain the FastMCP dependencies **Example Configuration**: ```json { "mcpServers": { "cc-multi-process": { "command": "/Users/username/git/cc-multi-process-mcp/venv/bin/python3", "args": ["/Users/username/git/cc-multi-process-mcp/main.py"], "description": "Claude Code Multi-Process MCP Server - Provides parallel task execution capabilities" } } } ``` ### 3. Restart Claude Code Reload or restart Claude Code to load the MCP server. The server should appear in your available tools. ## API Reference ### `execute_cc_task` Execute Claude Code task synchronously, blocks until completion. **Parameters:** - `prompt` (required): Task description - `working_dir` (optional): Working directory - `model` (optional): "sonnet", "opus", or "haiku" - `skip_permissions` (optional): Skip permission checks (default: true) - `timeout` (optional): Timeout in seconds **Returns:** JSON string containing execution results ### `start_cc_task_async` Start Claude Code task asynchronously, returns task ID immediately. **Parameters:** - `prompt` (required): Task description - `working_dir` (optional): Working directory - `model` (optional): "sonnet", "opus", or "haiku" - `skip_permissions` (optional): Skip permission checks (default: true) - `timeout` (optional): Timeout in seconds **Returns:** Task ID string ### `check_task_status` Check asynchronous task status. **Parameters:** - `task_id` (required): Task ID **Returns:** JSON string containing task status and results ### `list_active_tasks` List all currently active tasks. **Returns:** JSON string containing active task list ### `cleanup_task` Clean up specified task and its related data. **Parameters:** - `task_id` (required): Task ID to clean up **Returns:** JSON string containing cleanup results ## Usage Examples ### Asynchronous Execution Example (Recommended) ```python # Start a long-running background task task_id = start_cc_task_async( prompt="Analyze all Python files and generate a comprehensive report", working_dir="/path/to/project", model="sonnet", skip_permissions=True ) # ✅ Returns immediately with Task ID: abc12345 # Continue your work while Claude Code runs in background # ... do other things ... # Check result when ready result = check_task_status(task_id) ``` ### Parallel Execution Example ```python # Start multiple tasks simultaneously task1 = start_cc_task_async( prompt="Generate unit tests for utils.py" ) task2 = start_cc_task_async( prompt="Refactor database.py to use async/await" ) task3 = start_cc_task_async( prompt="Add type hints to all functions in api.py" ) # All three tasks run in parallel # Check results when ready result1 = check_task_status(task1) result2 = check_task_status(task2) result3 = check_task_status(task3) ``` ### Synchronous Execution Example For simple tasks that need immediate results: ```python result = execute_cc_task( prompt="Write a Python function to validate email addresses", skip_permissions=True ) # ⏳ Blocks until completion, then returns result ``` ### Task Management Example ```python # List all active tasks active_tasks = list_active_tasks() # Clean up specific task cleanup_result = cleanup_task("task_id_here") # Check task status status = check_task_status("task_id_here") ``` ## Technical Implementation ### Architecture **Framework**: FastMCP + JSON-RPC over stdio **Language**: Python 3.6+ **Storage**: Filesystem-based task persistence (`/tmp/cc_process_tasks/`) **Process Management**: SIGCHLD signal handler prevents zombie processes **Logging**: Detailed logging to `/tmp/cc_process_mcp.log` ### Core Components - **TaskManager Class** - Manages task lifecycle and processes - **Asynchronous Process Management** - Uses subprocess.Popen to create non-blocking child processes - **Signal Handling** - Automatic resource cleanup and zombie process reclamation - **Filesystem State** - Task result persistent storage ### Design Decisions 1. **FastMCP-Based** - Uses modern MCP framework instead of raw JSON-RPC implementation 2. **Filesystem Persistence** - Task state stored in files, supports server restart 3. **Automatic Process Cleanup** - Unix signal handling prevents resource leaks 4. **Comprehensive Logging** - Complete execution logs for debugging and monitoring 5. **Task Isolation** - Each task uses separate directory and process ## Troubleshooting ### Installation Issues **"externally-managed-environment" error?** - This is expected on macOS. You must use a virtual environment: ```bash python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` **Dependencies not found?** - Ensure virtual environment is activated before installing - Verify FastMCP installation: `pip list | grep fastmcp` - Recreate virtual environment if needed: `rm -rf venv && python3 -m venv venv` ### Server Connection Issues **Server not showing up in Claude Code?** - Verify virtual environment Python path in configuration - Check that absolute paths are used for both command and args - Ensure virtual environment exists: `ls -la venv/bin/python3` - Test server manually: `./venv/bin/python3 main.py` - Restart Claude Code after configuration changes **ModuleNotFoundError: No module named 'fastmcp'?** - MCP server is using system Python instead of virtual environment - Update configuration to use `/path/to/project/venv/bin/python3` - Ensure dependencies were installed in the virtual environment ### Task Execution Issues **Task stuck in "running" status?** - Wait a moment, large tasks take time - Check task directory: `ls -la /tmp/cc_process_tasks/` - View logs: `tail -f /tmp/cc_process_mcp.log` - Verify Claude Code CLI is accessible: `which claude` **Processes not cleaning up properly?** - Use `cleanup_task` tool for manual cleanup - Check system processes: `ps aux | grep claude` - Restart server to force cleanup of all resources ### Permission Issues **Permission denied errors?** - Ensure virtual environment has proper permissions: `chmod +x venv/bin/python3` - Check that main.py is executable: `chmod +x main.py` - Verify write permissions to `/tmp/` directory ## System Requirements - **Python 3.6+** with virtual environment support - **Claude Code CLI** installed and accessible via PATH - **Unix/Linux/macOS** (supports signal handling) - **Virtual Environment** (required on modern macOS due to PEP 668) - **Write permissions** to `/tmp/` directory for task storage ## License MIT License