Skip to main content
Glama
Mannu-Thakur

Expense MCP Server

by Mannu-Thakur
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

💸 Expense MCP Server

A production-ready Model Context Protocol (MCP) server for managing personal expenses — built with FastMCP, SQLAlchemy, and Pydantic. Deploys as a Docker container on Render with PostgreSQL, and connects to Claude Desktop, Cursor, VS Code, or any MCP-compatible client.

Status

✅ Live on Render — Docker · PostgreSQL · Streamable HTTP

Transport

Streamable HTTP

Database

PostgreSQL (Render managed)

Health endpoint

/health

MCP endpoint

/mcp

Related MCP server: Expense Tracker MCP

Architecture

Claude Desktop / Cursor / VS Code MCP
            │
            │  MCP over Streamable HTTP
            ▼
   ┌─────────────────────┐
   │  Expense MCP Server │  Docker · Render
   │  FastMCP + Uvicorn  │
   └────────┬────────────┘
            │
            ▼
   ┌─────────────────────┐
   │   Expense Service   │  Business logic
   └────────┬────────────┘
            │
            ▼
   ┌─────────────────────┐
   │     Repository      │  Data access layer
   └────────┬────────────┘
            │
            ▼
   ┌─────────────────────┐
   │  SQLAlchemy ORM     │
   └────────┬────────────┘
            │
            ▼
   ┌─────────────────────┐
   │  PostgreSQL / SQLite│  Prod / Dev
   └─────────────────────┘

API Request Flow

Claude  →  MCP Tool  →  FastMCP  →  Expense Service  →  Repository  →  SQLAlchemy  →  PostgreSQL

✨ Features

  • 8 MCP Tools — add, list, update, delete, search expenses, and get monthly/category/merchant summaries

  • Dual transport — STDIO (local Claude Desktop) and Streamable HTTP (remote/Docker/Render)

  • Dual database — SQLite for local development, PostgreSQL for production

  • Production-ready — structured logging, custom exceptions, connection pooling, non-root Docker user

  • 31 tests — full repository, service, and tool coverage with in-memory SQLite isolation

  • One-command deploy — render.yaml Blueprint auto-provisions PostgreSQL + Docker web service

Production Features

Feature

Detail

✓ Docker multi-stage image

Minimal, hardened runtime layer

✓ PostgreSQL

Render-managed with connection pooling

✓ Render Blueprint

Auto-provisions all infrastructure

✓ Health endpoint

/health for Render and load balancer checks

✓ Remote HTTP MCP

Accessible at /mcp from any MCP client

✓ Connection pooling

pool_size=5, max_overflow=10, pool_recycle=1800

✓ Structured logging

ISO timestamps, log levels, logger names

✓ Non-root container

appuser with no escalation

✓ Automatic DB provisioning

Tables created on first startup

Compatible Clients

✅ Claude Desktop
✅ Cursor
✅ VS Code MCP extension
✅ Any MCP client supporting Streamable HTTP

Transport Modes

Transport

When to use

stdio

Local Claude Desktop — server runs as a child process

streamable-http

Remote deployment, Docker, Render — server listens on HTTP

🗂 Project Structure

expense-mcp-server/
├── app/
│   ├── config.py              # Pydantic Settings (reads from .env)
│   ├── exceptions.py          # ExpenseNotFoundError, ExpenseValidationError
│   ├── logging_config.py      # Structured logging setup
│   ├── mcp_instance.py        # FastMCP instance + /health endpoint
│   ├── server.py              # Registers all 8 tools
│   ├── database/
│   │   ├── db.py              # Engine, SessionLocal, validate_connection()
│   │   └── models.py          # Expense SQLAlchemy model
│   ├── schemas/
│   │   └── expense.py         # ExpenseCreate, ExpenseUpdate (Pydantic)
│   ├── repositories/
│   │   └── expense_repository.py
│   ├── services/
│   │   └── expense_service.py
│   ├── tools/
│   │   ├── add_expense.py
│   │   ├── list_expenses.py
│   │   ├── update_expense.py
│   │   ├── delete_expense.py
│   │   ├── search_expenses.py
│   │   ├── monthly_summary.py
│   │   ├── category_summary.py
│   │   └── top_merchants.py
│   └── utils/
│       ├── dates.py
│       └── currency.py
├── tests/
│   ├── conftest.py            # In-memory SQLite fixtures + monkeypatch
│   └── test_expense.py        # 31 tests
├── run.py                     # Entry point
├── requirements.txt
├── Dockerfile                 # Multi-stage Docker build
├── docker-compose.yml         # App + PostgreSQL local stack
├── render.yaml                # Render Blueprint (PostgreSQL + Docker web service)
└── .env                       # Local environment variables

🛠 MCP Tools

Tool

Description

add_expense

Add a new expense with amount, category, date, merchant, currency

list_expenses

List all expenses sorted by date descending

update_expense

Update any field of an existing expense by ID

delete_expense

Delete an expense by ID

search_expenses

Search by category, description, or merchant

monthly_summary

Total, count, average, and max for the current month

category_summary

Spending totals grouped by category

top_merchants

Top merchants by total spending

⚙️ Environment Variables

Variable

Default

Description

APP_ENV

development

development or production

LOG_LEVEL

INFO

Python log level

MCP_SERVER_NAME

Expense Tracker

Name shown in Claude Desktop

TRANSPORT

stdio

stdio or streamable-http

HOST

0.0.0.0

Bind host (HTTP mode only)

PORT

8000

Bind port for local/Docker. Render injects PORT=10000 automatically — no manual configuration needed.

DATABASE_URL

sqlite:///./expenses.db

SQLite or PostgreSQL connection string

🚀 Getting Started

Option A — Local Development (STDIO + SQLite)

1. Clone and create a virtual environment

git clone https://github.com/your-username/expense-mcp-server.git
cd expense-mcp-server
python -m venv .venv

2. Activate the virtual environment

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure .env

APP_ENV=development
LOG_LEVEL=INFO
MCP_SERVER_NAME=Expense Tracker
TRANSPORT=stdio
HOST=0.0.0.0
PORT=8000
DATABASE_URL=sqlite:///./expenses.db

5. Run the server

python run.py

The server starts in STDIO mode — ready to be used with Claude Desktop.

Option B — Local Docker + PostgreSQL (HTTP)

1. Start the full stack

docker-compose up --build

This starts:

  • expense_postgres — PostgreSQL 16 on port 5432

  • expense_mcp — MCP server on port 8000 (Streamable HTTP transport)

The app waits for PostgreSQL to pass its health check before starting.

2. Verify it's running

curl http://localhost:8000/health

Option C — Deploy to Render (Docker + PostgreSQL)

The project deploys as a Docker multi-stage image on Render.

1. Push your repo to GitHub

2. Go to render.com → New → Blueprint

3. Connect your GitHub repo — Render auto-detects render.yaml and automatically creates:

  • A managed PostgreSQL database

  • A Docker web service running run.py

  • All required environment variables

  • Database connection wired via fromDatabase.connectionString

4. Your server will be live at:

https://<your-render-service>.onrender.com

Replace <your-render-service> with your actual Render service name (shown in the dashboard after deployment).

🔍 Health Check

The server exposes /health for Render and load balancer health checks.

curl https://<your-render-service>.onrender.com/health

Response:

{"status": "ok"}

🔌 Verify the MCP Endpoint

GET https://<your-render-service>.onrender.com/mcp

Note: A browser will show 405 Method Not Allowed. This is expected — /mcp speaks the MCP protocol (not plain HTTP GET). Use an MCP client to connect.

🖥 Claude Desktop Configuration

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or
~/Library/Application Support/Claude/claude_desktop_config.json (macOS).

Option A — Local STDIO

{
  "mcpServers": {
    "expense-tracker": {
      "command": "C:\\path\\to\\expense-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\expense-mcp-server\\run.py"]
    }
  }
}

Option B — Render (Remote HTTP)

{
  "mcpServers": {
    "expense-tracker": {
      "type": "streamable-http",
      "url": "https://<your-render-service>.onrender.com/mcp"
    }
  }
}

Option C — Docker (Local HTTP)

{
  "mcpServers": {
    "expense-tracker": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

You can include all three entries simultaneously — just give each a unique key.

🧪 Running Tests

python -m pytest tests/ -v

Expected output:

31 passed in ~1s

The test suite covers:

  • TestExpenseRepository — 13 tests (CRUD + search + summaries)

  • TestExpenseService — 10 tests (business logic + error handling)

  • TestTools — 8 tests (MCP tool integration)

Tests use an in-memory SQLite database with full transaction rollback isolation between each test.

🗃 Database

SQLite (Local)

Zero configuration. The expenses.db file is created automatically on first run.

DATABASE_URL=sqlite:///./expenses.db

PostgreSQL (Docker / Production)

DATABASE_URL=postgresql://expense_user:expense_pass@localhost:5432/expense_db

The Expense table is created automatically via Base.metadata.create_all() on startup.

Column

Type

Notes

id

Integer

Primary key

amount

Float

Required, must be > 0

category

String

Required

description

String

Optional

merchant

String

Optional

payment_method

String

Optional

currency

String

Default: INR

expense_date

Date

Required

created_at

DateTime

Auto-set to UTC now

📦 Tech Stack

Layer

Library

Version

MCP Framework

mcp (FastMCP)

1.28.1

Settings

pydantic-settings

2.14.2

ORM

SQLAlchemy

2.0.51

Validation

pydantic

2.13.4

PostgreSQL driver

psycopg2-binary

2.9.10

HTTP server

uvicorn + starlette

—

Testing

pytest

9.1.1

📄 License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • expense-tracker-remote-mcp

    MuazamAbbas
    F
    license
    B
    quality
    D
    maintenance
    A remote MCP server for expense tracking, providing tools to add, list, update, delete expenses, and generate summaries, budget status, and monthly trends.
    8
    -

  • Expense Tracker MCP

    ayush-patel-29
    F
    license
    Not graded
    quality
    B
    maintenance
    A simple MCP server for tracking expenses in a local SQLite database, enabling add, read, update, delete, and summarization of expenses with predefined categories.
    -

  • Smart Expense Management MCP

    neev-25
    F
    license
    B
    quality
    B
    maintenance
    An AI-powered MCP server for personal and group expense management, providing CRUD operations, advanced filtering, analytics, Splitwise-style splitting, budget tracking, and report generation.
    38
    -

  • Expense_Tracker_MCP

    satyam0singh
    A
    license
    Not graded
    quality
    B
    maintenance
    A production-grade MCP server for personal finance management, enabling AI agents to add, update, search expenses, manage budgets and credit cards, and generate financial reports.
    2
    MIT