claude-code-parallel-mcp-server

MCP (Model Context Protocol) server that wraps Claude Code's headless mode with parallel task spawning capabilities.

Overview

This MCP server enables Claude Desktop to automatically spawn multiple headless Claude Code sessions in parallel, significantly improving performance when handling independent tasks.

Features

• Parallel Execution: Spawn multiple Claude Code sessions simultaneously
• Automatic Task Distribution: Claude Desktop automatically uses parallel spawning when appropriate
• Full Claude Code Capabilities: Each spawned session has complete access to file operations, bash commands, and code analysis
• JSON Output: Structured results from all parallel sessions

Requirements

• Node.js 18.0.0 or higher
• Claude Code CLI installed and available in PATH
  • Install from: https://code.claude.com
  • Verify: claude --version

Installation

Via npx (Recommended)

No installation needed! Use directly with npx:

npx claude-code-parallel-mcp-server

Global Installation

npm install -g claude-code-parallel-mcp-server

Usage with Claude Desktop

Add to your Claude Desktop MCP server configuration:

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "claude-code": {
      "command": "npx",
      "args": ["claude-code-parallel-mcp-server"],
      "env": {}
    }
  }
}

Restart Claude Desktop after adding the configuration.

How It Works

When Claude Desktop connects to this MCP server, it gains access to two tools:

1. spawn_claude_session

Spawns a single headless Claude Code session.

Parameters:

• task (required): Task description to send to Claude Code
• allowedTools (optional): Comma-separated list of allowed tools
• disallowedTools (optional): Comma-separated list of disallowed tools
• appendSystemPrompt (optional): Additional system instructions

Example:

{
  "task": "Analyze package.json for security vulnerabilities",
  "allowedTools": "Read,Bash"
}

2. spawn_parallel_claude_sessions

Spawns multiple headless Claude Code sessions in parallel.

Parameters:

• tasks (required): Array of task descriptions
• asyncMode (optional): If true, returns immediately and writes results to files. Use for large-scale operations (10+ tasks). Default: false
• outputDirectory (optional): Directory path for results (with asyncMode=true). Default: ~/Desktop/claude-code-results
• allowedTools (optional): Comma-separated list of allowed tools for all sessions
• disallowedTools (optional): Comma-separated list of disallowed tools
• appendSystemPrompt (optional): Additional system instructions for all sessions

Example (Standard Mode - Small Batches):

{
  "tasks": [
    "Analyze security vulnerabilities",
    "Check performance issues",
    "Review code quality"
  ]
}

Example (Async Mode - Large Scale):

{
  "tasks": [
    "Analyze security in authentication module",
    "Review API endpoint performance",
    "Check database query efficiency",
    ... more tasks ...
  ],
  "asyncMode": true,
  "outputDirectory": "/Users/username/Desktop/analysis-results"
}

When to Use Async Mode:

• 10+ parallel tasks
• Long-running analyses (2+ minutes per task)
• Large-scale batch processing operations
• Want to avoid MCP timeouts
• Need to monitor progress in real-time by watching output directory

Claude Desktop will automatically use spawn_parallel_claude_sessions when it identifies multiple independent tasks.

Example Usage

Once configured in Claude Desktop, simply ask Claude to perform tasks:

Single Task:

"Analyze the authentication module for security issues"

Parallel Tasks (automatically detected):

"Check my codebase for security vulnerabilities, performance problems, and code quality issues"

Claude will spawn 3 parallel sessions, execute them simultaneously, and present unified results.

Performance

• Sequential: Task 1 → Task 2 → Task 3 (sum of execution times)
• Parallel: Task 1 + Task 2 + Task 3 (max of execution times)

For 3 tasks taking 2 minutes each: 6 minutes → 2 minutes (3x faster!)

Large-Scale Batch Processing (Async Mode)

For processing 10+ files or long-running tasks, use async mode to avoid MCP timeouts:

How it works:

1. Claude Desktop calls the MCP server with asyncMode: true
2. MCP server spawns all tasks immediately (supports many parallel sessions)
3. Returns instantly with output directory path
4. Each session writes its result to a separate file
5. Monitor progress in real-time by watching the directory

Example - Large-Scale Processing:

Ask Claude Desktop:

"Analyze all source files in the src/ directory for security issues using async mode.
Write results to ~/Desktop/security-analysis"

Claude Desktop will:

1. Call spawn_parallel_claude_sessions with asyncMode: true
2. Get immediate response: "Tasks started, results in ~/Desktop/security-analysis"
3. Display the output directory to you

You can then:

• Open Finder and navigate to ~/Desktop/security-analysis
• Watch files appear as analyses complete: result-001-*.html, result-002-*.html, etc.
• Check for any errors in error-*.txt files
• All analyses run in parallel (limited only by system resources)

Output Files:

• Results: result-001-1703123456789.html (task 1, timestamp)
• Errors: error-042-1703123456789.txt (task 42 failed, timestamp)

Benefits:

• No MCP timeout (response is instant)
• Scale to many parallel sessions
• Real-time progress visibility
• Easy error debugging
• Results persist on disk

Output Format

Returns JSON with:

• totalTasks: Number of tasks executed
• executionTimeMs: Total execution time in milliseconds
• results: Array of results from each session
  • taskIndex: Index of the task
  • taskDescription: Original task description
  • status: "success" or "error"
  • result or error: Session output or error message

Troubleshooting

"claude: command not found"

Claude Code CLI is not installed or not in PATH.

Solution:

# Install Claude Code
# Visit: https://code.claude.com

# Verify installation
claude --version

"Server disconnected"

Check Claude Desktop logs:

• macOS: ~/Library/Logs/Claude/
• Windows: %APPDATA%\Claude\logs\

Permission Issues

Ensure Node.js has permission to spawn child processes and execute claude command.

Development

Local Testing

# Clone/download the package
cd claude-code-parallel-mcp-server

# Install dependencies
npm install

# Test the server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node index.js

Running Locally

npm start

The server communicates via stdio (standard input/output) using the MCP protocol.

Architecture

Claude Desktop
    ↓ (MCP Protocol)
claude-code-parallel-mcp-server
    ↓ (spawns processes)
Multiple headless Claude Code sessions (parallel)
    ↓ (execute tasks)
Results aggregated and returned

Security

• Each spawned Claude Code session respects Claude Code's security model
• No elevated privileges required
• Executes with the same permissions as the user running Claude Desktop
• All file operations follow standard system permissions

License

MIT

Contributing

Contributions welcome! Please open issues or pull requests on GitHub.

Related Projects

• Claude Code - Official Claude Code CLI
• Model Context Protocol - MCP specification
• MCP SDK - JavaScript/TypeScript SDK

Support

For issues with:

• This MCP server: Open an issue on GitHub
• Claude Code: Visit https://code.claude.com
• MCP Protocol: Visit https://modelcontextprotocol.io

Changelog

1.0.1 (2025-12-17)

• Initial release
• Parallel task spawning with async mode support
• Support for allowedTools, disallowedTools, appendSystemPrompt
• Async mode for large-scale batch processing
• Output directory configuration for async results
• JSON output format