GeiserX/cashpilot-mcp

cashpilot-mcp

A tiny bridge that exposes any CashPilot instance as an MCP server, enabling LLMs to monitor passive income earnings, manage services, and control fleet workers.

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