home / mcp / expense tracker mcp server

Expense Tracker MCP Server

Provides an AI-powered expense backend with natural language interface, intelligent categorization, and real-time data sync via MCP and Gemini.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "keyurgit45-expense-tracker-mcp": {
      "command": "python",
      "args": [
        "run_mcp.py"
      ],
      "env": {
        "SUPABASE_KEY": "YOUR_SUPABASE_KEY",
        "SUPABASE_URL": "YOUR_SUPABASE_URL",
        "GOOGLE_API_KEY": "YOUR_GOOGLE_API_KEY"
      }
    }
  }
}

This expense tracking backend provides an MCP server that exposes core expense management tools through a Model Context Protocol, paired with a Gemini AI server that offers a chat-based interface and authentication. You can manage expenses, automatically categorize transactions, and get real-time insights with secure access and learn-from-use improvements.

How to use

You interact with the MCP server through an MCP client or integration that supports Model Context Protocol calls. Use the chat interface to issue natural language commands like creating expenses, requesting spend summaries, or analyzing subscriptions. The Gemini AI server handles authentication and natural language processing, while the MCP server executes the underlying tools and data operations.

How to install

Prerequisites: you need Python 3.8+ and a supported operating system with access to install packages.

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Environment setup

Create a local environment file and populate the required credentials.

cp .env.example .env
# Add your credentials:
# - SUPABASE_URL
# - SUPABASE_KEY
# - GOOGLE_API_KEY (for Gemini)

Database setup

Set up the necessary database schemas by executing the provided SQL scripts in your Supabase SQL Editor to enable core tables and embeddings support.

# Core tables
scripts/create_tables.sql
# Embeddings support
scripts/create_embeddings_schema.sql

Run both servers

Start the MCP server and the Gemini AI server in separate terminals.

# Terminal 1: MCP Server
python run_mcp.py

# Terminal 2: Gemini AI Server
uvicorn app.servers.gemini.main:app --reload --port 8000

Initialize data

Populate predefined hierarchical categories and tags to enable structured expense organization.

# Populate categories
python scripts/populate_hierarchical_categories.py

# Populate predefined tags
python scripts/populate_predefined_tags.py

API endpoints you’ll use

Use the chat interface to send natural language commands via POST /chat, and refresh tokens via POST /auth/refresh. Through the MCP tools exposed by the MCP server, you can create expenses from natural language, auto-categorize transactions, get spending summaries, analyze subscriptions, and view recent transactions.

Available tools

Create expenses

Convert natural language prompts into expense records and populate core fields like amount, date, merchant, and category.

Auto-categorize transactions

Assign or refine categories using embeddings, similarity matching, and learned rules to improve accuracy.

Get spending summaries

Provide aggregated insights such as totals by category, period, or merchant to help you understand spending patterns.

Analyze subscriptions

Identify recurring payments and detect subscription-based expenses for easier management.

View recent transactions

Retrieve the most recent transactions for quick review and auditing.