drumsergio/cashpilot-mcp repository overview

⁠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

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⁠