# mcp-expense-tracker

An MCP (Model Context Protocol) server for tracking expenses. Expenses are stored in a local JSON file, and the server exposes tools for adding expenses and summarizing totals by day or month.

Two equivalent implementations are included:

- **`src/`** — TypeScript/Node, stdio transport. Use this with Claude Code or Claude Desktop.
- **`server.py`** — Python (FastMCP). Use this to deploy on [FastMCP Cloud](https://fastmcp.cloud) so it's reachable as a remote connector from claude.ai.

## Tools

- **add_expense** — record an expense (`amount`, `category`, optional `description`, optional `date` defaulting to today)
- **list_expenses** — list expenses, optionally filtered by `start_date`, `end_date`, `category`
- **delete_expense** — delete an expense by `id`
- **summarize** — get the total (and per-category breakdown) for a `day`, `month`, or `all` time, anchored on an optional `date`

## Deploy on FastMCP Cloud (for claude.ai)

FastMCP Cloud deploys directly from this GitHub repo. When it asks for an **entrypoint**, use:

```
server.py
```

(FastMCP Cloud auto-detects the `mcp` object in `server.py`; you'd only need `server.py:mcp` if the variable were named something else.) It installs `requirements.txt` automatically. Once deployed, add the resulting `https://<your-app>.fastmcp.app/mcp` URL as a custom connector in claude.ai's connector settings.

**Storage caveat:** `server.py` stores expenses in a local `data/expenses.json` file. Confirm your FastMCP Cloud plan gives that container a persistent disk — if storage is ephemeral/rebuilt on redeploy, expenses will reset. If you hit that, swap `server.py`'s file-backed storage for a hosted database.

## Node/TypeScript setup

```bash
npm install
npm run build
```

## Run standalone

```bash
npm start
```

The server communicates over stdio, so it's meant to be launched by an MCP client rather than used directly in a terminal.

## Use with Claude Code

```bash
claude mcp add expense-tracker -- node /absolute/path/to/mcp-tracker/build/index.js
```

## Use with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-tracker/build/index.js"]
    }
  }
}
```

## Run the Python version locally

```bash
pip install -r requirements.txt
python server.py
```

## Data storage

Expenses are stored in `data/expenses.json` (created automatically). Set `EXPENSE_DATA_DIR` to change where data is stored. This applies to both implementations.