CashChat

CashChat MCP Server enables you to expose your CashChat financial data to AI assistants using the Model Context Protocol (MCP). It supports both remote URL-based connections secured with OAuth 2.0 and local stdio connections, giving you flexible deployment options for testing, development, and production workflows with Claude Desktop or other MCP-compatible assistants.

How to use

You can use the CashChat MCP Server in two main modes. For a remote, cloud-based setup, connect your MCP client via the URL-based HTTP/SSE flow with OAuth 2.0 authentication. This lets Claude Desktop or other MCP-enabled assistants securely access your transactions, summaries, and settings through a public endpoint. For local or private setups, run the server as a local process using stdio, which communicates over standard input and output without an HTTP layer.

URL-based connections require you to authenticate using OAuth 2.0. You will configure your MCP client with the server URL and the OAuth endpoints, then authorize the connection once prompted. The server exposes endpoints for authenticating users, streaming data, and performing actions on transactions and analytics. After authorizing, you can start asking your AI assistant for insights, such as spending summaries or adding transactions, and the assistant will relay those requests to the MCP server.

Local stdio mode is ideal for development or environments without an accessible public URL. In this mode, your client runs the MCP server as a child process and communicates via the standard input and output streams. No HTTP server or OAuth is required in this configuration.

How to install

Prerequisites you need to prepare before installing: Node.js 18 or higher, npm or yarn, and a CashChat API key.

Step 1: Clone the project repository.

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

Step 2: Install dependencies.

npm install

Step 3: Configure environment variables. Create a local environment file and add your CashChat API key.

cp .env.example .env

Edit .env and replace with your API key and port configuration.

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

Step 4: Build the project.

npm run build

Step 5: Start the server.

npm run start:server

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

Notes on deployment and usage

If you want to test OAuth in a local environment, you may need an HTTPS tunnel such as ngrok or localtunnel so your OAuth redirect URIs can be publicly reachable.

Security and access control

The server supports OAuth 2.0 with PKCE for secure authorization, Bearer token authentication for API requests, and scope-based permissions (read/write). Use HTTPS in production and rotate API keys regularly.

Available tools

get_transactions

Retrieve transactions with optional filters such as date range, category, limit, and offset.

add_transaction

Create a new transaction with amount, category, date, and optional fields like type, note, and merchant name.

update_transaction

Update an existing transaction by ID with new values for amount, category, note, or merchant name.

delete_transaction

Delete a transaction by ID.

get_summary

Get a spending summary for a specified period (day, week, month, or year) with an optional reference date.

get_categories

List all available transaction categories.

get_settings

Retrieve the current CashChat settings.

update_settings

Update CashChat settings such as preferredCurrency and agentInstructions.