# 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)](https://modelcontextprotocol.io). 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](https://cashchat.supastellar.dev) 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`
```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:**
```bash
git clone https://github.com/supastellar/cashchat-mcp
cd cashchat-mcp
```
2. **Install dependencies:**
```bash
npm install
```
3. **Configure environment variables:**
```bash
cp .env.example .env
```
Edit `.env` and add your CashChat API key:
```env
CASHCHAT_API_KEY=your_api_key_here
PORT=3000
SERVER_URL=http://localhost:3000
```
4. **Build the project:**
```bash
npm run build
```
5. **Start the server:**
```bash
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:
```json
{
"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](https://ngrok.com/) or [localtunnel](https://localtunnel.me/).
---
## Legacy stdio Mode (for local-only setup)
If you prefer the classic stdio-based local connection without OAuth:
### Claude Desktop Config (stdio mode)
```json
{
"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](./DEPLOYMENT.md).
### Quick Deployment Options
#### Railway (Recommended)
[](https://railway.app/template/cashchat-mcp)
1. Click the button above
2. Add your `CASHCHAT_API_KEY`
3. Deploy!
#### Cloudflare Workers
```bash
npm install -g wrangler
wrangler login
wrangler secret put CASHCHAT_API_KEY
wrangler deploy
```
See [DEPLOYMENT.md](./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
1. Use HTTPS only (no HTTP in production)
2. Set `OAUTH_CLIENT_SECRET` for additional security
3. Implement rate limiting
4. Use a proper database for token storage (not in-memory)
5. Rotate API keys regularly
6. 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](./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:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
---
## License
MIT License - see [LICENSE](./LICENSE) for details.
---
## Links
- **CashChat:** https://cashchat.supastellar.dev
- **MCP Documentation:** https://modelcontextprotocol.io
- **Claude Desktop:** https://claude.ai/download
- **GitHub:** https://github.com/supastellar/cashchat-mcp
- **Issues:** https://github.com/supastellar/cashchat-mcp/issues
---
## Support
Need help?
- 📖 Check the [DEPLOYMENT.md](./DEPLOYMENT.md) guide
- 🐛 Report bugs on [GitHub Issues](https://github.com/supastellar/cashchat-mcp/issues)
- 💬 Questions? Open a [Discussion](https://github.com/supastellar/cashchat-mcp/discussions)
---
**Built with ❤️ by [Supa Stellar](https://supastellar.dev)**
