# Expense Tracker MCP Server

A lightweight, async **Model Context Protocol (MCP)** server that lets any MCP-compatible AI assistant (like Claude) add, list, and summarize your personal expenses — backed by SQLite.

Built with [FastMCP](https://gofastmcp.com/) and deployed on **FastMCP Cloud**.

🔗 **Live MCP endpoint:** `https://slippery-tomato-sawfish.fastmcp.app/mcp`

---

## What it does

Once connected, an AI assistant can manage your expenses conversationally — no forms, no spreadsheets. Just say "add ₹500 for groceries" or "summarize my July spending" and it happens.

## Tools

| Tool | Description |
|---|---|
| `add_expense(date, amount, category, subcategory="", note="")` | Adds a new expense entry to the database |
| `list_expenses(start_date, end_date)` | Lists all expenses within an inclusive date range, most recent first |
| `summarize(start_date, end_date, category=None)` | Groups and totals expenses by category within a date range |

## Resources

- `expense:///categories` — Returns the list of supported expense categories as JSON.

## Tech Stack

- **[FastMCP](https://gofastmcp.com/)** — MCP server framework
- **aiosqlite** — fully async SQLite driver (no blocking calls on the event loop)
- **SQLite** — simple, file-based storage (auto-initialized on first run)

## Why async?

Every tool (`add_expense`, `list_expenses`, `summarize`) is defined with `async def` and uses `aiosqlite` under the hood. This means the server doesn't block while waiting on database I/O — multiple requests can be handled concurrently instead of queuing behind a single synchronous call.

## Database

The database (`expenses.db`) is created automatically in the system's temp directory on first run, with the following schema:

```sql
CREATE TABLE expenses(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT DEFAULT '',
    note TEXT DEFAULT ''
)
```

WAL journal mode is enabled for better concurrent read/write performance.

## Running Locally

```bash
pip install fastmcp aiosqlite

python server.py
```

By default this starts an HTTP server on `0.0.0.0:8000`. To run over stdio instead (for local MCP clients), swap the `mcp.run(...)` call at the bottom of the file.

## Deploying

This server is deployed on **FastMCP Cloud**, which handles hosting the HTTP transport and gives you a public MCP URL you can plug into any MCP client (Claude, etc.) — no need to manage your own server or ngrok tunnel.

## Connecting from Claude

Add the MCP endpoint as a connector:

```
https://slippery-tomato-sawfish.fastmcp.app/mcp
```

Once connected, just talk to it naturally:
> "Add an expense of ₹450 for groceries today"
> "Show me my expenses from this month"
> "Summarize my spending by category"

## Roadmap / Ideas

- [ ] Edit/delete expense entries
- [ ] Monthly budget limits + alerts
- [ ] Export to CSV
- [ ] Multi-user support with auth

---

*Built as a hands-on project to learn the Model Context Protocol — from local server to a deployed, always-on tool an AI assistant can actually use.*