Skip to main content
Glama
rmstxrx

Maestro MCP

by rmstxrx
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

🎼 Maestro MCP

An Opus is a piece that deserves to be held by an Orchestra, conducted by a proper Maestro.

Maestro is an MCP server that turns a heterogeneous machine fleet into a unified workspace for AI agents. SSH into any host, run commands across platforms, transfer files, and dispatch coding agents — all through a single orchestration layer.

Built for developers/power users who work across multiple machines and want their AI assistant to do the same.

Why Maestro?

Most MCP SSH servers connect to one host. You configure a hostname, a key, and you're in.

But that's not how real setups work. You have a GPU box running Linux, a MacBook for travel, a Windows workstation with WSL — each with different shells, different paths, different capabilities. You don't just need SSH. You need a conductor that understands the whole orchestra.

Maestro gives your AI agent the same mental model you have: named hosts, persistent connections, cross-platform awareness, and the ability to dispatch long-running tasks to coding agents while continuing the conversation.

Related MCP server: MCP SSH Server

Features

  • Named hosts with per-host shell awareness (Bash, PowerShell, WSL)

  • SSH ControlMaster lifecycle — persistent multiplexed connections with auto-reconnect and exponential backoff

  • Local routing — the hub machine bypasses SSH entirely for zero-overhead local execution

  • Dual-mode execution — inline commands (20s, synchronous) for quick ops, staged scripts (async, tmux) for long-running tasks

  • Direct file I/O — read and write small files (≤4 KB) over SSH with hard timeouts

  • Transfer relay — push/pull larger files via HTTP endpoints with Bearer token auth

  • Fleet status — one-command health check across all hosts with auto-reconnection

  • Agent orchestra — dispatch Codex CLI, Gemini CLI, or Claude Code as async background tasks with ledger tracking, live observation, and steering

  • Task ledger — persistent task history surviving restarts, with automatic 30-day pruning

  • Remote access (optional) — OAuth 2.1 with PIN-gated consent for exposing Maestro over HTTP (e.g., from Claude.ai via Cloudflare Tunnel)

Architecture

Maestro runs on one hub machine — the one with SSH access to all others. Star topology: every host is one hop from the hub. The hub itself is marked is_local: true and executes locally with no SSH overhead.

Dispatched agents (Codex, Gemini, Claude Code) run in hub-local tmux windows that SSH into the target host. The orchestrator can observe their output, send keystrokes, and stop them — all without entering the agent's context.

              AI Agent (Claude.ai / Claude Code / Codex CLI)
                         │
                    MCP protocol
                    (stdio or HTTP)
                         │
                  ┌──────┴──────┐
                  │   Maestro   │  ← hub machine (is_local: true)
                  │  ┌────────┐ │
                  │  │ ledger │ │     persistent task history
                  │  └────────┘ │
                  │  ┌────────┐ │
                  │  │  tmux  │ │     agent dispatch windows
                  │  └────────┘ │
                  └──┬───┬───┬──┘
                     │   │   │
              SSH ControlMaster pool
                     │   │   │
                ┌────┘   │   └────┐
                ▼        ▼        ▼
            linux-box  win-pc   macbook
            (bash)     (pwsh)   (bash)
                         │
                         └─► WSL (ProxyCommand)

Quick Start

Prerequisites

  • Python 3.12+

  • SSH configured with ~/.ssh/config entries for your remote hosts (ControlMaster recommended)

  • MCP SDK (pip install "mcp[cli]")

1. Clone and install

git clone https://github.com/rmstxrx/maestro-mcp.git
cd maestro-mcp

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Define your fleet

Copy the example config and edit it. CRITICAL: hosts.yaml and .env contain sensitive data (IPs, hostnames, PIN hashes, and tokens). They are git-ignored by default. Never commit these files or hardcode sensitive topology details if you plan to push your fork to a public repository.

cp hosts.example.yaml hosts.yaml
# hosts.yaml — define your machine fleet
hosts:
  workstation:
    alias: ssh-workstation        # must match a Host entry in ~/.ssh/config
    description: "Main dev box, Arch Linux"
    is_local: true                # hub machine — no SSH, direct execution

  gpu-box:
    alias: ssh-gpu
    description: "Training rig, Ubuntu 24.04"
    # shell: bash (default)

  macbook:
    alias: ssh-macbook
    description: "MacBook Pro, on the go"

  windows-pc:
    alias: ssh-winpc
    description: "Windows 11, PowerShell"
    shell: powershell

  windows-wsl:
    alias: ssh-winpc-wsl
    description: "WSL2 on windows-pc (ProxyCommand)"
    # shell: bash (default)

3. Set up authentication

# Generate a PIN hash for the OAuth consent gate
python -c "import hashlib; pin = input('Choose a PIN: '); print(hashlib.sha256(pin.encode()).hexdigest())"

Create your .env file:

cp .env.example .env
# Edit .env and paste your PIN hash
# .env
MAESTRO_AUTHORIZE_PIN_HASH="your_sha256_hash_here"
SSH_TIMEOUT=300
MAESTRO_ISSUER_URL=https://your-domain.example.com  # Required for HTTP transport
# MAESTRO_TRANSFER_ALLOWED_DIRS="~/,/tmp"           # Paths the relay can write to
# MAESTRO_DEFAULT_REPO=~/workspace                   # Default working dir for agents

4. Run

# Local MCP client (stdio transport, for Codex CLI / Claude Code / Claude Desktop)
.venv/bin/python server.py --transport stdio

# Remote/cloud access (HTTP transport, for Claude.ai via tunnel)
.venv/bin/python server.py --transport streamable-http --port 8222 --host 127.0.0.1

5. Connect your AI client

Claude Code:

claude mcp add maestro -- /path/to/maestro-mcp/.venv/bin/python /path/to/maestro-mcp/server.py --transport stdio

Codex CLI:

codex mcp add maestro -- /path/to/maestro-mcp/.venv/bin/python /path/to/maestro-mcp/server.py --transport stdio

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "maestro": {
      "command": "/path/to/maestro-mcp/.venv/bin/python",
      "args": ["/path/to/maestro-mcp/server.py", "--transport", "stdio"]
    }
  }
}

Claude.ai (via Cloudflare Tunnel or similar): Point the MCP connector to your tunnel URL. OAuth consent is handled automatically for Claude.ai clients.

Tools Reference

Fleet Tools

Tool

Description

exec

Execute on any host. Inline mode (command=): synchronous SSH, 20s hard timeout, returns stdout/stderr directly. Staged mode (task_id=): runs a pre-staged script in tmux, returns task_id for polling.

read

Read a file from any host (≤4 KB, 10s timeout). Returns content directly.

write

Write a file to any host (≤4 KB, 10s timeout). Content piped via stdin.

status

Fleet health check with auto-reconnect. Optional agents=True to probe CLI availability.

service

Start a long-running process (vLLM, Jupyter, etc.). No hard ceiling — runs until stopped.

observe

Capture live output from a running task's tmux pane (~50 lines).

steer

Send keystrokes to a running task (approval prompts, Ctrl+C, input).

stop

Kill a running task's tmux window. Updates the ledger.

Agent Orchestra

Tool

Description

dispatch

Dispatch a coding agent (Codex, Gemini, or Claude Code) to any host. Runs in a hub-local tmux window. Returns task_id for tracking.

poll

Check status of a dispatched task. Shows elapsed time and overtime flag.

tasks

List recent tasks from the persistent ledger. Filter by status, agent, host, or task type.

prepare_relay

Get an ephemeral Bearer token (1h TTL) for the HTTP file transfer relay.

gemini_sessions

List previous Gemini CLI sessions on a host.

Execution Tiers

Tier

Tool

Timeout

Use case

1

read / write

10s

File I/O under 4 KB

2

exec inline

20s

Quick commands, no reasoning needed

3

exec staged

6h

Long scripts, builds, deployments

4

dispatch

6h

Agent tasks requiring reasoning

File Transfer

Maestro provides two mechanisms for moving files:

Direct I/O (read/write) — for small files (≤4 KB). Uses SSH, returns content in the tool response. Fast, simple, one tool call.

Transfer relay (prepare_relay + HTTP push/pull) — for larger files. The relay endpoints accept multipart uploads and stream downloads, authenticated with ephemeral Bearer tokens. This keeps large file content out of the LLM context window.

# Get a relay token (via MCP tool)
# prepare_relay → {"value": "abc123...", "ttl_seconds": 3600}

# Push a file to a host
curl -H "Authorization: Bearer abc123..." \
  -F "file=@local_file.py" \
  "https://your-maestro/transfer/push?host=gpu-box&remote_path=/home/user/file.py"

# Pull a file from a host
curl -H "Authorization: Bearer abc123..." \
  -o local_file.py \
  "https://your-maestro/transfer/pull?host=gpu-box&remote_path=/home/user/file.py"

SSH Configuration Tips

Maestro relies on your existing ~/.ssh/config. Here's a recommended setup for fleet usage:

# Global: enable ControlMaster for all hosts
Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600
    ServerAliveInterval 30
    ServerAliveCountMax 3

# Direct hosts
Host ssh-gpu
    HostName 192.168.1.100
    User dev

Host ssh-macbook
    HostName macbook.local
    User user

# Windows host (PowerShell over OpenSSH)
Host ssh-winpc
    HostName 192.168.1.200
    User admin

# WSL via ProxyCommand through Windows host
Host ssh-winpc-wsl
    User user
    ProxyCommand ssh ssh-winpc "wsl -d Ubuntu -e nc localhost 22"
# Don't forget to create the sockets directory
mkdir -p ~/.ssh/sockets

Deployment

Docker Compose (recommended for HTTP transport)

services:
  maestro:
    build: .
    container_name: maestro
    restart: unless-stopped
    ports:
      - "8222:8222"
    env_file:
      - ./config/.env
    volumes:
      - ./config/ssh:/mnt/ssh:ro          # SSH keys and config
      - ./config/hosts.yaml:/app/hosts.yaml:ro
      - ./state:/root/.maestro            # Task ledger, OAuth state
      # For is_local hub: mount host paths the relay needs to access
      # - /home/user/workspace:/home/user/workspace
      # - /tmp/maestro:/tmp/maestro

Exposing via Cloudflare Tunnel

If you want Claude.ai to reach your Maestro instance:

cloudflared tunnel --url http://localhost:8222

Or as a persistent named tunnel — see Cloudflare's documentation.

As a systemd service (stdio or HTTP)

# /etc/systemd/system/maestro.service
[Unit]
Description=Maestro MCP Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/maestro-mcp
EnvironmentFile=/path/to/maestro-mcp/.env
ExecStart=/path/to/maestro-mcp/.venv/bin/python server.py --transport streamable-http --port 8222
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Project Structure

maestro-mcp/
├── server.py                  # Entry point — FastMCP wiring, routes, middleware
├── maestro/
│   ├── tools/
│   │   ├── fleet.py           # Fleet tools: exec, read, write, status, observe, steer, stop, service
│   │   └── orchestra.py       # Agent dispatch: codex, gemini, claude, poll, tasks, prepare_relay
│   ├── client.py              # Client classification (remote/local/LAN/stdio)
│   ├── config.py              # MaestroConfig from environment
│   ├── hosts.py               # Host registry, status tracking, command wrapping
│   ├── mux.py                 # Hub-local tmux multiplexer for agent dispatch
│   ├── relay.py               # HTTP file transfer relay (push/pull/task results)
│   └── transport.py           # SSH execution layer (async_run, retries, connection lifecycle)
├── maestro_oauth.py           # OAuth 2.1 provider with PIN-gated consent
├── oauth_rewrite.py           # URL rewrite middleware for multi-origin OAuth
├── hosts.yaml                 # Your fleet definition (git-ignored)
├── hosts.example.yaml         # Example fleet config
├── .env                       # Secrets — PIN hash, tokens (git-ignored)
├── .env.example               # Template for .env
├── docker-compose.yml         # Docker deployment config
├── Dockerfile                 # Container build
├── requirements.txt           # Python dependencies
└── LICENSE                    # Apache 2.0

Gotchas

  • Claude.ai tool filtering: Claude.ai's MCP connector can silently filter tools whose name or description suggests credential generation. If a tool disappears from discovery, inspect the tool name and description for terms like token, secret, key, auth, bearer, or credential, then rename and sanitize. The filtering is intent-based, not pure keyword matching.

  • Tool definition caching: After rebuilding the Maestro container, you must fully disconnect and reconnect the MCP connector in Claude.ai settings. Tool definitions are cached at the OAuth session level.

  • Context budget: Tool responses consume LLM context. Use exec with grep, head, tail, jq for surgical reads. Use read only for files under 4 KB. For larger files, use the transfer relay — the response is just {"status": "ok"}, near-zero context cost.

Origin

Maestro was born from necessity. I work across multiple machines — a Linux box for inference, a Windows PC for training, and a MacBook for when I'm away from the desk. I got tired of my AI assistant only seeing one machine at a time while I had to manually bridge the gaps.

What started as a simple SSH relay grew into a full orchestration layer: persistent connections, cross-platform shell awareness, agent dispatch, and eventually OAuth for remote access from Claude.ai. The name came naturally — if the models are the instruments, someone needs to conduct.

License

Apache 2.0 — use it freely, contribute fearlessly, and don't weaponize patents.

Contributing

Contributions are welcome. If you're building something with Maestro, I'd love to hear about it.

For bug reports and feature requests, open an issue. For code contributions, please open a PR with a clear description of what changed and why.

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rmstxrx/maestro-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server