CashPilot MCP Server

A Model Context Protocol (MCP) server that gives AI assistants access to freelancer finance tools powered by Stripe.

Tools

| Tool | Description | |------|-------------| | get_revenue_summary | Total revenue for a date range (auto-paginates) | | get_profit_summary | Net profit after Stripe fees and refunds | | list_invoices | List invoices with filtering by status | | create_invoice | Create a draft invoice for a customer | | send_invoice | Finalize and send a draft invoice | | list_overdue_invoices | Open invoices past their due date | | list_clients | List Stripe customers | | get_client_revenue | Revenue breakdown per client (auto-paginates) | | get_balance | Current Stripe balance (available + pending) | | cash_flow_forecast | Project 30/60/90-day cash position from invoices + subscriptions | | list_expenses | List payouts and refunds (money going out) | | create_expense | Record an expense via Stripe product metadata |

Setup

npm install
cp .env.example .env
# Add your Stripe secret key to .env

Usage

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "cashpilot": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/cashpilot",
      "env": {
        "STRIPE_SECRET_KEY": "sk_..."
      }
    }
  }
}

Development

npm run dev      # Run with tsx (hot reload)
npm run build    # Compile TypeScript
npm test         # Run tests (41 test cases)
npm run lint     # Type-check without emitting

Project Structure

src/
  index.ts              # MCP server entry point (stdio transport)
  tools/
    revenue.ts          # get_revenue_summary
    reporting.ts        # get_profit_summary, cash_flow_forecast
    invoices.ts         # list_invoices, create_invoice, send_invoice, list_overdue_invoices
    clients.ts          # list_clients, get_client_revenue
    balance.ts          # get_balance
    expenses.ts         # list_expenses, create_expense
  utils/
    stripe.ts           # Lazy Stripe client singleton
    format.ts           # Currency, date, and status formatting
tests/
  format.test.ts        # Formatting utility tests
  stripe.test.ts        # Stripe client tests
  tools/
    revenue.test.ts     # Revenue tool tests
    reporting.test.ts   # Profit summary tests
    forecast.test.ts    # Cash flow forecast tests
    invoices.test.ts    # Invoice tool tests (all 4 tools)
    clients.test.ts     # Client tool tests
    balance.test.ts     # Balance tool tests
    expenses.test.ts    # Expense tool tests
.github/
  workflows/
    ci.yml              # GitHub Actions CI (Node 20/22)