It talks to your own CashPilot instance with its API key, over stdio or Streamable HTTP.

Speaks MCP 2026-07-28 and every earlier revision down to 2024-11-05 from the same binary: current clients that still use the initialize handshake (Claude Code, Claude Desktop, Cursor, VS Code) and 2026-07-28 clients (server/discover, stateless requests) both work.

Features

• Earnings: totals, per-service balances with cashout eligibility, daily series and history.
• Fleet: deployed services, the deployable catalog, workers, health scores and collector alerts, as tools and as cashpilot:// resources.
• Service control on any worker: start, stop, restart, deploy, remove, logs, plus trigger_collection and a Docker Compose export per architecture.
• Read-only mode: CASHPILOT_READ_ONLY=true registers only the tools that change nothing.
• Every tool has a title and read-only/destructive hints, list tools return structured JSON, inputs are validated.
• HTTP mode listens on 127.0.0.1:8081, checks Origin, caps request size and requires MCP_AUTH_TOKEN on any non-loopback address.

Install

Every snippet runs the npm package over stdio. Use the admin key (CASHPILOT_ADMIN_API_KEY) for full control, or the read-only key (CASHPILOT_READONLY_API_KEY) with CASHPILOT_READ_ONLY=true. Never the fleet key.

Claude Code

claude mcp add --transport stdio --env CASHPILOT_URL=http://localhost:8080 --env CASHPILOT_API_KEY=<key> cashpilot -- npx -y cashpilot-mcp

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

{
  "mcpServers": {
    "cashpilot": {
      "command": "npx",
      "args": ["-y", "cashpilot-mcp"],
      "env": {
        "CASHPILOT_URL": "http://localhost:8080",
        "CASHPILOT_API_KEY": "<key>"
      }
    }
  }
}

VS Code (.vscode/mcp.json; the key is asked once and stored by VS Code)

{
  "inputs": [
    { "id": "cashpilot-key", "type": "promptString", "description": "CashPilot API key", "password": true }
  ],
  "servers": {
    "cashpilot": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "cashpilot-mcp"],
      "env": { "CASHPILOT_URL": "http://localhost:8080", "CASHPILOT_API_KEY": "${input:cashpilot-key}" }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.cashpilot]
command = "npx"
args = ["-y", "cashpilot-mcp"]
env = { CASHPILOT_URL = "http://localhost:8080", CASHPILOT_API_KEY = "<key>" }

Docker, the HTTP server and local builds are in Getting started; every variable is in Configuration.

Tools

| Tool | What it does | Changes the fleet | |------|--------------|-------------------| | get_earnings_summary | Totals: today, this month, all time | no | | get_earnings_breakdown | Balance and cashout eligibility per service | no | | get_earnings_daily | One total per day, 1 to 365 days | no | | get_earnings_history | Records for a week, month, year or all | no | | list_deployed_services | What runs where, with status and resources | no | | list_available_services | Deployable catalog with the env keys each needs | no | | get_fleet_summary | Workers and containers, online and total | no | | list_workers | Worker ids for worker_id | no | | get_health_scores | Health per service over 1 to 90 days | no | | get_collector_alerts | Errors from the last earnings collection | no | | get_service_logs | Latest container log lines (untrusted content) | no | | get_compose | docker-compose.yml for amd64, arm64 or arm | no | | trigger_collection | Collect earnings now, in the background | yes | | start_service / restart_service | Start or restart a container | yes | | stop_service | Stop a container; it stops earning | yes, destructive | | deploy_service | Deploy or redeploy with env, hostname, instances | yes, destructive | | remove_service | Remove a deployment; volumes are kept | yes, destructive |

With more than one worker online, service tools need worker_id (from list_workers). Resources and details are in Usage.

Documentation

• Getting started: Docker Compose, npm, local build
• Configuration: environment variables and MCP client configuration
• Usage: resources and tools
• Development: testing, contributing, credits
• Related projects: the family and registry listings

Related projects

CashPilot, the passive income fleet manager this server talks to.

License

GPL-3.0-or-later