orchestrator-mcp 0.1.0
MCP server for Tmux Aider Orchestrator - control multiple AI agents from Claude
Requires Python: >=3.11
Keywords: ai-agents, aider, claude, mcp, ollama, orchestrator, tmux

# orchestrator-mcp

MCP server for [Tmux Aider Orchestrator](https://github.com/kouji648-hub/tmux-aider-orchestrator) — control multiple local AI agents (Aider + Ollama) from Claude Code or Claude MAX.

## Features

- **27 MCP tools** — task execution, workflows, pipelines (DAG), monitoring, git, system management
- **6 MCP resources** — state, metrics, pipelines, results, templates, projects
- **Dual transport** — stdio (Claude Code) and streamable-http (Claude MAX / remote)
- **Cloudflare Tunnel** — one-command script to expose your local orchestrator to Claude MAX
- **Auto-generated auth token** — secure HTTP mode with Bearer token

## Prerequisites

- Python 3.11+
- [Tmux Aider Orchestrator](https://github.com/kouji648-hub/tmux-aider-orchestrator) installed (`~/bin/orchestrate.sh`)
- [Ollama](https://ollama.ai/) with models (e.g., `qwen2.5-coder:32b`, `deepseek-r1:32b`)
- [Aider](https://aider.chat/) configured with Ollama
- tmux session with `ai`, `air`, and `bash` panes

## Installation

```bash
# From PyPI
pip install orchestrator-mcp

# From source
git clone https://github.com/kouji648-hub/orchestrator-mcp.git
cd orchestrator-mcp
pip install -e .
```

## Usage

### Claude Code (stdio mode)

Add to `~/.mcp.json`:

```json
{
  "mcpServers": {
    "orchestrator": {
      "command": "python",
      "args": ["-m", "orchestrator_mcp"]
    }
  }
}
```

Or with custom orchestrate.sh path:

```json
{
  "mcpServers": {
    "orchestrator": {
      "command": "python",
      "args": ["-m", "orchestrator_mcp"],
      "env": {
        "ORCHESTRATOR_SCRIPT": "/path/to/orchestrate.sh"
      }
    }
  }
}
```

### Claude MAX (HTTP + Cloudflare Tunnel)

#### Quick Start

```bash
# One command — starts server + tunnel
./scripts/start-tunnel.sh
```

This will:
1. Start the MCP HTTP server on port 8888
2. Auto-generate a Bearer auth token
3. Launch a Cloudflare Tunnel (free, no account needed)
4. Print the tunnel URL for Claude MAX

#### Manual Setup

```bash
# Start HTTP server (auto-generates auth token)
python -m orchestrator_mcp --transport http --port 8888

# In another terminal, start Cloudflare Tunnel
cloudflared tunnel --url http://localhost:8888
```

#### Connect Claude MAX

1. Copy the Cloudflare tunnel URL (e.g., `https://xxx-xxx.trycloudflare.com`)
2. Open [Claude MAX](https://claude.ai) > Settings > Connectors
3. Click **Add Connector**
4. Enter URL: `https://xxx-xxx.trycloudflare.com/mcp`
5. Done! You can now use orchestrator tools in Claude MAX

### CLI Options

```
python -m orchestrator_mcp [OPTIONS]

Options:
  --transport {stdio,http}  Transport mode (default: stdio)
  --host HOST               HTTP host (default: 0.0.0.0)
  --port PORT               HTTP port (default: 8888)
  --token TOKEN             Bearer token for HTTP auth
  --no-auth                 Disable auth (use only behind trusted tunnel)
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ORCHESTRATOR_SCRIPT` | `~/bin/orchestrate.sh` | Path to orchestrate.sh |
| `ORCHESTRATOR_TIMEOUT` | `300` | Default command timeout (seconds) |
| `ORCHESTRATOR_STATE_BASE` | `/tmp/aider_orchestrator` | State directory |
| `ORCHESTRATOR_HOST` | `0.0.0.0` | HTTP server host |
| `ORCHESTRATOR_PORT` | `8888` | HTTP server port |
| `ORCHESTRATOR_AUTH_TOKEN` | (auto-generated) | Bearer auth token |

## Tools Reference

### Task Execution (6 tools)

| Tool | Description |
|------|-------------|
| `orchestrator_task_run` | Run a task on a specific pane (ai/air/bash) |
| `orchestrator_task_dispatch` | Auto-route task to best pane by keyword |
| `orchestrator_task_smart` | Smart execution with auto file detection + retry |
| `orchestrator_task_ask_team` | Ask both AI agents and compare answers |
| `orchestrator_task_review` | Auto code review on uncommitted changes |
| `orchestrator_task_parallel` | Run multiple tasks in parallel |

### Workflow (3 tools)

| Tool | Description |
|------|-------------|
| `orchestrator_workflow_run` | Run named workflow (implement-review, design-implement, etc.) |
| `orchestrator_workflow_template_run` | Run workflow template with variables |
| `orchestrator_workflow_template_list` | List available templates |

### Pipeline (5 tools)

| Tool | Description |
|------|-------------|
| `orchestrator_pipeline_create` | Create a new pipeline |
| `orchestrator_pipeline_add_step` | Add step with dependencies |
| `orchestrator_pipeline_run` | Run pipeline (DAG parallel execution) |
| `orchestrator_pipeline_status` | Show pipeline status |
| `orchestrator_pipeline_visualize` | Generate Mermaid DAG diagram |

### Monitoring (7 tools)

| Tool | Description |
|------|-------------|
| `orchestrator_status` | Full orchestrator state |
| `orchestrator_health` | Health check for all panes |
| `orchestrator_pane_idle` | Check if pane is idle |
| `orchestrator_metrics` | Performance metrics |
| `orchestrator_results` | Recent task results |
| `orchestrator_log` | Session log entries |
| `orchestrator_search` | Search task history |

### Git (3 tools)

| Tool | Description |
|------|-------------|
| `orchestrator_git_snapshot` | Save git state for rollback |
| `orchestrator_git_diff` | Show uncommitted changes |
| `orchestrator_git_commit` | Auto-commit with message |

### System (3 tools)

| Tool | Description |
|------|-------------|
| `orchestrator_selftest` | Run full self-test |
| `orchestrator_report` | Generate session report |
| `orchestrator_pane_restart` | Restart an Aider pane |

## Resources

| URI | Description |
|-----|-------------|
| `orchestrator://state` | Current state.json |
| `orchestrator://metrics` | Performance metrics |
| `orchestrator://pipelines` | Pipeline definitions |
| `orchestrator://results/latest` | Latest task results |
| `orchestrator://templates` | Workflow templates |
| `orchestrator://projects` | Active projects |

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run server in dev mode
python -m orchestrator_mcp --transport http --port 8888 --no-auth
```

## Architecture

```
Claude Code / Claude MAX
        |
        | MCP Protocol (stdio or streamable-http)
        v
  orchestrator-mcp (FastMCP)
        |
        | asyncio subprocess
        v
   orchestrate.sh (bash)
        |
        | tmux send-keys
        v
  ┌─────┴──────┐
  │  tmux panes │
  ├─────────────┤
  │ ai  (Qwen)  │
  │ air (R1)     │
  │ bash         │
  └──────────────┘
        |
        v
    Ollama (local LLM)
```

## License

MIT