CashChat MCP Server

CashChat MCP Server

Connect your financial data to AI assistants like Claude

CashChat MCP Server exposes your CashChat financial data to AI assistants via the Model Context Protocol (MCP). It supports both local stdio connections and remote URL-based connections with OAuth 2.0 authentication.

Features

• 🔐 OAuth 2.0 Authentication - Secure URL-based connections for Claude Desktop
• 💰 Transaction Management - Query, add, update, and delete transactions
• 📊 Financial Analytics - Get spending summaries and category breakdowns
• ⚙️ Settings Control - Manage currency preferences and AI agent instructions
• 🚀 Multiple Deployment Options - Run locally, Node.js server, or Cloudflare Workers
• 🔌 MCP Standard Compliant - Works with any MCP-compatible AI assistant

Quick Start

For Claude Desktop Users (URL-based connection)

This is the recommended way to connect CashChat to Claude Desktop using a publicly accessible server.

1. Get Your CashChat API Key

Sign up at CashChat and get your API key from the settings page.

2. Connect to the Public Server

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cashchat": {
      "url": "https://cashchat.supastellar.dev/sse",
      "oauth": {
        "authUrl": "https://cashchat.supastellar.dev/oauth/authorize",
        "tokenUrl": "https://cashchat.supastellar.dev/oauth/token",
        "clientId": "cashchat-mcp-server",
        "scopes": ["read", "write"]
      }
    }
  }
}

3. Restart Claude Desktop

Restart Claude Desktop and you'll be prompted to authorize the connection. Click "Authorize" and you're ready to go!

4. Try It Out

In Claude Desktop, try asking:

• "What did I spend on groceries this month?"
• "Add a transaction: $50 for dinner at Joe's Restaurant"
• "Show me my spending summary for this week"

Local Development & Self-Hosting

Prerequisites

• Node.js 18 or higher
• npm or yarn
• CashChat API key

Installation

1. Clone the repository:

git clone https://github.com/supastellar/cashchat-mcp
cd cashchat-mcp

2. Install dependencies:

npm install

3. Configure environment variables:

cp .env.example .env

Edit .env and add your CashChat API key:

CASHCHAT_API_KEY=your_api_key_here
PORT=3000
SERVER_URL=http://localhost:3000

4. Build the project:

npm run build

5. Start the server:

npm run start:server

The server will be running at http://localhost:3000.

Testing Locally

Connect Claude Desktop to your local server by updating the config:

{
  "mcpServers": {
    "cashchat": {
      "url": "http://localhost:3000/sse",
      "oauth": {
        "authUrl": "http://localhost:3000/oauth/authorize",
        "tokenUrl": "http://localhost:3000/oauth/token",
        "clientId": "cashchat-mcp-server",
        "scopes": ["read", "write"]
      }
    }
  }
}

Note: Claude Desktop may require HTTPS for OAuth. For local testing with HTTPS, use a tool like ngrok or localtunnel.

Legacy stdio Mode (for local-only setup)

If you prefer the classic stdio-based local connection without OAuth:

Claude Desktop Config (stdio mode)

{
  "mcpServers": {
    "cashchat": {
      "command": "node",
      "args": ["/absolute/path/to/cashchat-mcp/build/index.js"],
      "env": {
        "CASHCHAT_API_KEY": "your_api_key_here"
      }
    }
  }
}

This mode runs the server as a subprocess and communicates via stdin/stdout. No HTTP server or OAuth required.

Available Tools

The MCP server provides 8 tools for interacting with your financial data:

Transaction Tools

`get_transactions`

Retrieve transactions with optional filters.

Parameters:

• startDate (optional): Start date (YYYY-MM-DD)
• endDate (optional): End date (YYYY-MM-DD)
• category (optional): Filter by category
• limit (optional): Max results (default: 50)
• offset (optional): Pagination offset

Example:

Get my transactions from January 2024

`add_transaction`

Add a new transaction.

Parameters:

• amount (required): Transaction amount
• category (required): Category (e.g., Food, Transport)
• date (required): Date (YYYY-MM-DD)
• type (optional): 'expense' or 'income' (default: expense)
• note (optional): Description
• name (optional): Merchant name

Example:

Add a transaction: $75 for groceries at Whole Foods on 2024-01-15

`update_transaction`

Update an existing transaction.

Parameters:

• id (required): Transaction ID
• amount (optional): New amount
• category (optional): New category
• note (optional): New note
• `na