claude-code-orchestrator-mcp by jan-raap - MCP Server

Claude Code Orchestrator MCP

MCP Server to orchestrate Claude Code one-off commands with task queue and workflow support.

Features

Task Queue: Queue multiple Claude Code tasks with max 3 concurrent executions
MCP Integration: Use from VS Code, Claude Desktop, or any MCP-compatible client
Workflow Support: Create multi-step workflows with task dependencies
Async Execution: Non-blocking task creation with status polling
Process Management: Automatic timeout handling and process watchdog

Installation

# Clone and install
git clone https://github.com/jan-raap/claude-code-orchestrator-mcp.git
cd claude-code-orchestrator-mcp
npm install
npm run build

Configuration

Add to your .claude/mcp.json:

{
  "mcpServers": {
    "claude-code-orchestrator": {
      "command": "node",
      "args": [
        "D:\\machen\\html\\claude\\claude-code-orchestrator-mcp\\dist\\index.js"
      ]
    }
  }
}

MCP Tools

`create_task`

Create and queue a Claude Code task for execution.

{
  prompt: string,          // Required: Task prompt for Claude
  model?: "opus" | "sonnet" | "haiku",
  allowedTools?: string[], // Restrict tools for security
  workingDir?: string,     // Execution context
  timeout?: number,        // Max execution time (ms)
  priority?: number        // Task priority (default: 0)
}

`get_task_status`

Get the current status of a task.

{
  taskId: string  // Required
}

`list_tasks`

List all tasks with optional filtering.

{
  status?: "queued" | "running" | "completed" | "failed",
  limit?: number,   // Default: 20
  offset?: number   // Default: 0
}

`cancel_task`

Cancel a queued or running task.

{
  taskId: string  // Required
}

`get_task_result`

Get the full result output of a completed task.

{
  taskId: string,
  includeOutput?: boolean  // Default: true
}

`create_workflow`

Create a multi-step workflow with dependent tasks.

{
  tasks: Array<{
    name: string,
    prompt: string,
    dependsOn?: string[]  // Task names to wait for
  }>
}

Usage Examples

Simple Task

// Create task
const task = await mcp.callTool("create_task", {
  prompt: "Analyze the codebase and create a summary report",
  workingDir: "/path/to/project",
  allowedTools: ["Read", "Glob", "Grep"]
});

// Poll for completion
let status;
do {
  await sleep(2000);
  status = await mcp.callTool("get_task_status", {
    taskId: task.taskId
  });
} while (status.status === "running");

// Get result
const result = await mcp.callTool("get_task_result", {
  taskId: task.taskId
});

Workflow

const workflow = await mcp.callTool("create_workflow", {
  tasks: [
    {
      name: "analyze",
      prompt: "Analyze codebase structure"
    },
    {
      name: "refactor",
      prompt: "Refactor based on analysis",
      dependsOn: ["analyze"]
    },
    {
      name: "test",
      prompt: "Run tests and fix failures",
      dependsOn: ["refactor"]
    }
  ]
});

Configuration

Edit config.json to customize:

{
  "claude": {
    "executable": "claude",
    "defaultModel": "sonnet",
    "defaultTimeout": 300000
  },
  "queue": {
    "maxConcurrent": 3,      // Max parallel Claude processes
    "maxQueueSize": 100,     // Max queued tasks
    "retryAttempts": 1       // Retry failed tasks
  }
}

Architecture

src/
├── index.ts                    # MCP Server entry
├── types.ts                    # TypeScript types
├── config.ts                   # Config loader
├── queue/
│   ├── TaskQueue.ts            # Task queue manager
│   ├── Task.ts                 # Task class
│   └── TaskStatus.ts           # Status enums
├── executor/
│   ├── ClaudeExecutor.ts       # Claude process spawner
│   └── OutputParser.ts         # Stream-JSON parser
└── tools/
    ├── createTask.ts
    ├── getTaskStatus.ts
    ├── listTasks.ts
    ├── cancelTask.ts
    ├── getTaskResult.ts
    └── createWorkflow.ts

Known Issues

Process Hanging: Claude Code can hang when spawned from Node.js. Workaround: Process watchdog with aggressive timeout.
Stream-JSON Parsing: May fail on malformed output. Workaround: Robust parser with fallback to text mode.

Development

# Watch mode
npm run dev

# Build
npm run build

# Run
npm start

License

MIT

Author

Jan Raap - janraap.de