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.

2. Configure Claude Code

Add to your ~/.claude/settings.json:

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:

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)

Parallel Execution Example

Synchronous Execution Example

For simple tasks that need immediate results:

Task Management Example

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:

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