Expense Tracker MCP Server

A simple MCP (Model Context Protocol) server that lets an AI assistant (like Claude) add, list, and summarize your personal expenses — backed by a persistent Turso (libSQL) database, deployed on Render.

Instead of manually opening a spreadsheet, you can just tell your AI assistant things like "Add ₹500 for food" or "Show my expenses this month", and it calls this server to actually store and fetch the data.

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools over a common interface. An MCP server exposes a set of tools (functions) that the assistant can invoke, with typed inputs and structured outputs.

In this project:

• The assistant "sees" three tools: add_expense, list_expenses, summarize.

• When you ask something in plain language, the assistant picks the right tool, fills in the parameters, and calls this server.

• This server runs the actual database logic and returns a structured JSON result back to the assistant.

This means the assistant doesn't need to know how the database works — it just needs to know what tools are available and what they do.

Related MCP server: Expense Tracker MCP Server

What this server does

Built with FastMCP (a Python framework for building MCP servers) and Turso (a hosted libSQL/SQLite database) for storage.

Tools

Resource

• expense:///categories — returns the list of available expense categories as JSON (read from categories.json, falling back to a default list if missing).

Data stored per expense

• id — auto-incrementing primary key

• date — expense date

• amount — expense amount

• category — e.g. Food, Travel, Personal Care

• subcategory — optional finer detail (e.g. "Haircut")

• note — optional free-text note

How it works, step by step

1. Database: On first use, the server connects to a Turso database and creates the expenses table if it doesn't already exist.

2. Adding an expense: The add_expense tool inserts a row into the expenses table and returns the new row's ID.

3. Listing expenses: The list_expenses tool queries all rows between two dates (inclusive), most recent first.

4. Summarizing: The summarize tool groups expenses by category within a date range, returning the total amount and entry count per category (optionally filtered to a single category).

5. Serving over HTTP: The server runs with mcp.run(transport="http", ...), binding to the port Render provides via the PORT environment variable (defaults to 8000 locally).

Project structure

expense-tracker-mcp-server/
├── main.py            # Server entry point — defines the MCP tools and resource
├── categories.json    # Default list of expense categories
├── pyproject.toml     # Project metadata and dependencies
├── requirements.txt   # Pip-installable dependency list
├── uv.lock            # Locked dependency versions (uv package manager)
└── src/                # Additional source files

Setup

1. Prerequisites

• Python 3.10+

• A Turso database (free tier works fine)

• uv (recommended) or pip

2. Clone the repo

git clone https://github.com/Digam-hue/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server

3. Set environment variables

Create a .env file or export these directly:

export TURSO_DATABASE_URL="libsql://<your-db>.turso.io"
export TURSO_AUTH_TOKEN="<your-auth-token>"

These are required — the server will refuse to start without them.

4. Install dependencies

uv sync
# or
pip install -r requirements.txt

5. Run locally

python main.py

By default it serves on http://0.0.0.0:8000.

6. Deploy (this project uses Render)

• Push the repo to GitHub.

• Create a new Web Service on Render, pointing at this repo.

• Add TURSO_DATABASE_URL and TURSO_AUTH_TOKEN as environment variables in Render's dashboard.

• Render automatically sets PORT; no changes needed for that.

Connecting it to an AI assistant

Once deployed, add the server's URL (e.g. https://your-app.onrender.com/mcp) as an MCP connector in your assistant's settings. Once connected, you can just talk naturally:

• "Add ₹500 for food"

• "Show my expenses this month"

• "Summarize spending by category"

The assistant will call add_expense, list_expenses, or summarize accordingly and show you the result.

Notes

• All amounts are stored as-is with no currency conversion — pick one currency and stick to it.

• Categories are freeform strings; categories.json is just a suggested list, not an enforced schema.

• The database client is created lazily on first request (inside the server's event loop) to avoid async setup issues at import time.