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.

# 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:

{
  "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:

{
  "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)

# 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

# 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:

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

# 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:

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