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

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

Clone the repository:

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

Install dependencies:

npm install

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

Build the project:

npm run build

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
name (optional): New merchant name

`delete_transaction`

Delete a transaction.

Parameters:

id (required): Transaction ID to delete

Analytics Tools

`get_summary`

Get spending summary for a time period.

Parameters:

period (required): 'day', 'week', 'month', or 'year'
date (optional): Reference date (defaults to today)

Example:

Show me my spending summary for this month

`get_categories`

List all available transaction categories.

Example:

What categories can I use?

Settings Tools

`get_settings`

Get your CashChat settings.

`update_settings`

Update your CashChat settings.

Parameters:

preferredCurrency (optional): Currency code (USD, CAD, EUR, etc.)
agentInstructions (optional): Custom instructions for AI assistant

Deployment

For production deployment instructions, see DEPLOYMENT.md.

Quick Deployment Options

Railway (Recommended)

Click the button above
Add your CASHCHAT_API_KEY
Deploy!

Cloudflare Workers

npm install -g wrangler
wrangler login
wrangler secret put CASHCHAT_API_KEY
wrangler deploy

See DEPLOYMENT.md for detailed instructions.

Architecture

URL-Based Mode (HTTP + SSE + OAuth)

┌─────────────────┐          ┌──────────────────┐
│  Claude Desktop │          │  CashChat MCP    │
│                 │          │  Server (HTTP)   │
├─────────────────┤          ├──────────────────┤
│                 │          │                  │
│  1. OAuth Flow  │ ◄───────►│  /oauth/*        │
│                 │          │                  │
│  2. SSE Connect │ ◄───────►│  /sse            │
│                 │          │                  │
│  3. MCP Tools   │ ◄───────►│  MCP Server      │
│                 │          │                  │
└─────────────────┘          └────────┬─────────┘
                                      │
                                      ▼
                             ┌──────────────────┐
                             │  CashChat API    │
                             │  (Backend)       │
                             └──────────────────┘

Legacy stdio Mode

┌─────────────────┐          ┌──────────────────┐
│  Claude Desktop │          │  CashChat MCP    │
│                 │          │  Server (stdio)  │
├─────────────────┤          ├──────────────────┤
│                 │          │                  │
│  stdio pipe     │ ◄───────►│  MCP Server      │
│                 │          │                  │
└─────────────────┘          └────────┬─────────┘
                                      │
                                      ▼
                             ┌──────────────────┐
                             │  CashChat API    │
                             │  (Backend)       │
                             └──────────────────┘

Security

OAuth 2.0 with PKCE support for secure authorization
Bearer token authentication for API requests
HTTPS required in production
Token expiration (30 days default)
Scope-based permissions (read/write)

Production Security Recommendations

Use HTTPS only (no HTTP in production)
Set OAUTH_CLIENT_SECRET for additional security
Implement rate limiting
Use a proper database for token storage (not in-memory)
Rotate API keys regularly
Monitor access logs

Troubleshooting

"Connection refused" error

Check if the server is running
Verify the URL in your Claude Desktop config
Ensure firewall allows the port

OAuth authorization fails

Confirm SERVER_URL is publicly accessible
Check that URLs in Claude config match your server
Verify HTTPS is enabled (required by Claude Desktop)

"Invalid API key" error

Check your CASHCHAT_API_KEY is correct
Verify the API key is active in your CashChat account

Tools not showing up in Claude

Restart Claude Desktop after config changes
Check server logs for errors
Verify OAuth flow completed successfully

For more help, see DEPLOYMENT.md or open an issue.

Development

Project Structure

cashchat-mcp/
├── src/
│   ├── index.ts              # Legacy stdio server
│   ├── server.ts             # HTTP/SSE server with OAuth
│   ├── worker.ts             # Cloudflare Workers version
│   ├── types.ts              # TypeScript types
│   ├── api/
│   │   └── client.ts         # CashChat API client
│   ├── auth/
│   │   ├── tokenStore.ts     # OAuth token storage
│   │   ├── middleware.ts     # Auth middleware
│   │   └── oauthRoutes.ts    # OAuth endpoints
│   └── tools/
│       ├── transactions.ts   # Transaction tools
│       └── summary.ts        # Analytics tools
├── build/                    # Compiled JavaScript
├── package.json
├── tsconfig.json
├── wrangler.toml            # Cloudflare Workers config
└── README.md

Scripts

npm run build - Compile TypeScript
npm run dev - Watch mode for development
npm start - Run stdio server (legacy)
npm run start:server - Run HTTP/SSE server
npm run dev:server - Development mode with auto-reload

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see LICENSE for details.

Support

Need help?

📖 Check the DEPLOYMENT.md guide
🐛 Report bugs on GitHub Issues
💬 Questions? Open a Discussion

Built with ❤️ by Supa Stellar

cashchat-mcp

CashChat MCP Server

Features

Quick Start

For Claude Desktop Users (URL-based connection)

1. Get Your CashChat API Key

2. Connect to the Public Server

3. Restart Claude Desktop

4. Try It Out

Local Development & Self-Hosting

Prerequisites

Installation

Testing Locally

Legacy stdio Mode (for local-only setup)

Claude Desktop Config (stdio mode)

Available Tools

Transaction Tools

get_transactions

add_transaction

update_transaction

delete_transaction

Analytics Tools

get_summary

get_categories

Settings Tools

get_settings

update_settings

Deployment

Quick Deployment Options

Railway (Recommended)

Cloudflare Workers

Architecture

URL-Based Mode (HTTP + SSE + OAuth)

Legacy stdio Mode

Security

Production Security Recommendations

Troubleshooting

"Connection refused" error

OAuth authorization fails

"Invalid API key" error

Tools not showing up in Claude

Development

Project Structure

Scripts

Contributing

License

Links

Support

Reviews

`get_transactions`

`add_transaction`

`update_transaction`

`delete_transaction`

`get_summary`

`get_categories`

`get_settings`

`update_settings`