Cashpilot MCP

What GeiserX/cashpilot-mcp does

GeiserX/cashpilot-mcp bridges an existing CashPilot deployment to the Model Context Protocol. CashPilot is the system of record; the MCP process uses its admin API to expose fleet and earnings information to an MCP client.

The server covers passive-income and DePIN monitoring across CashPilot-managed sharing services. Read-only MCP resources provide summaries for earnings and fleet state, along with deployed services, the service catalog, workers, health scores, and collector alerts. Agents can therefore inspect the current state without turning every request into an API-specific workflow.

Operational actions are also available. The exposed tools support daily and historical earnings queries, service-log retrieval, and starting, stopping, restarting, deploying, or removing services. A collection can be triggered across all services, and a service's Docker Compose definition can be requested.

How it works

The process connects to the user's CashPilot instance over HTTP. Authentication uses CashPilot's administrator API key, specifically the admin key rather than the fleet key. MCP communication is available through a single /mcp JSON-RPC endpoint or through standard input and output.

HTTP mode listens on 127.0.0.1:8081 by default. When the endpoint is exposed beyond the local machine, MCP_AUTH_TOKEN can add bearer-token authentication. Stdio mode is selected with TRANSPORT=stdio, which fits clients that launch MCP servers as local subprocesses.

Setup and configuration

The npm package can be started with npx cashpilot-mcp. An MCP client configuration supplies the CashPilot URL and administrator API key as environment variables:

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

The same server is available as a Docker image and as multi-architecture Go binaries. HTTP deployment, Docker Compose configuration, and local builds are supported setup paths. Use TRANSPORT=stdio for stdio operation; otherwise the HTTP endpoint uses the default local listener. Set MCP_AUTH_TOKEN when bearer authentication is needed for an HTTP deployment.

Tools and capabilities

• Read earnings for daily or historical periods.
• Inspect logs for deployed services.
• Start, stop, restart, deploy, and remove CashPilot services.
• Trigger an earnings collection across all services.
• Retrieve a service's Docker Compose definition.
• Read resource data for earnings, fleet status, deployed services, the service catalog, workers, health scores, and collector alerts.

These capabilities combine monitoring with administrative control. Read-only resources are suitable for status queries, while service-management tools can change the deployed fleet and should be made available only to agents that are authorized to perform those operations.

Limitations and notes

The server requires access to a running CashPilot instance and a valid CashPilot admin API key. It is an interface to CashPilot rather than an independent earnings or fleet-management backend. The admin key should not be replaced with the fleet key.

The default HTTP listener is local to the host at 127.0.0.1:8081. Exposing it elsewhere requires attention to access control; MCP_AUTH_TOKEN provides bearer authentication for that case. Client setup examples use stdio, while HTTP clients can connect to the /mcp endpoint.