💸 Expense Tracker MCP Server

<div align="center">

A blazing-fast, AI-native Expense Tracker built as an MCP (Model Context Protocol) Server using FastMCP and SQLite.

Plug it directly into Claude Desktop, Cursor, or any MCP-compatible AI client — let your AI manage your finances for you.

</div>

---

📖 Table of Contents

• What is MCP?
• Features
• Project Structure
• Prerequisites
• Installation
• Running the Server
• Available Tools
• Connecting to Claude Desktop
• Development & Inspection
• Tech Stack

---

🤖 What is MCP?

The Model Context Protocol (MCP) is an open standard by Anthropic that allows AI models (like Claude) to securely interact with external tools, APIs, and data sources. This project exposes expense-tracking capabilities as MCP tools, meaning you can literally tell Claude:

"Add an expense: Coffee, $4.50, Food & Drink, Cash, 2026-08-02"

...and it will call this server and record it in your local SQLite database — no UI needed.

---

✨ Features

• 📝 Add Expenses — Record expenses with title, amount, category, payment method, date, and optional description
• 📋 List Expenses — Retrieve all stored expenses as structured data
• 🗄️ Persistent SQLite Storage — Auto-creates a local expenses.db database on first run
• ⚡ FastMCP Powered — Minimal boilerplate, maximum capability
• 🔍 Built-in Inspector — Visual tool inspector for debugging and testing
• 🔌 MCP-Compatible — Works with Claude Desktop, Cursor, and any MCP client

---

📁 Project Structure

expense_tracker_mcp_server/
├── expense_mcp_server.py      # 🎯 Main MCP server — all tools defined here
├── pyproject.toml             # Project metadata & dependencies
├── uv.lock                    # Locked dependency versions
├── .python-version            # Python version pin
├── .gitignore                 # Git ignore rules
├── src/
│   └── expense_tracker_mcp_server/
│       └── __init__.py        # Package entry point
└── README.md                  # You are here!

---

🛠️ Prerequisites

Make sure you have the following installed:

• Python 3.11+
• pip (comes with Python)
• uv — Fast Python package manager

---

🚀 Installation

Step 1 — Clone the Repository

git clone https://github.com/talha963/expense_mcp_server.git
cd expense_mcp_server

Step 2 — Install uv

pip install uv

Step 3 — Initialize the Project with uv

uv init .

Step 4 — Install FastMCP

# Via pip (global)
pip install fastmcp

# OR via uv (recommended — adds to project)
uv add fastmcp

Step 5 — Sync Dependencies

uv sync

---

▶️ Running the Server

Option 1 — Run directly with Python

python expense_mcp_server.py

Starts an HTTP server on http://0.0.0.0:8000

Option 2 — Run via uv

uv run expense_mcp_server.py

Option 3 — Run via FastMCP CLI (Recommended for MCP clients)

uv run --active fastmcp run expense_mcp_server.py

---

🔧 Available Tools

The server exposes the following MCP tools that AI models can call:

add_expense

Adds a new expense entry to the database.

Parameter	Type	Required	Description
title	string	✅	Name/title of the expense
amount	float	✅	Amount spent (e.g. 12.50)
category	string	✅	Category (e.g. Food, Transport)
payment_method	string	✅	e.g. Cash, Card, Online
expense_date	string	✅	Date in YYYY-MM-DD format
description	string	❌	Optional notes about the expense

Example response:

{
  "success": true,
  "expense_id": 1,
  "message": "Expense added successfully."
}

---

list_expenses

Returns all recorded expenses from the database.

No parameters required.

Example response:

[
  {
    "id": 1,
    "title": "Coffee",
    "amount": 4.5,
    "category": "Food & Drink",
    "payment_method": "Cash",
    "expense_date": "2026-08-02",
    "description": "Morning coffee at the office"
  }
]

---

🖥️ Connecting to Claude Desktop

To use this server with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "run",
        "--active",
        "fastmcp",
        "run",
        "/absolute/path/to/expense_mcp_server.py"
      ]
    }
  }
}

Config file location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

After saving, restart Claude Desktop and the Expense Tracker tools will appear automatically.

---

🔍 Development & Inspection

Use the FastMCP Inspector to visually test and explore your tools in the browser:

uv run --active fastmcp dev expense_mcp_server.py

This opens an interactive web UI where you can:

• See all registered tools
• Call tools manually with test inputs
• Inspect request/response payloads

---

🧰 Tech Stack

Technology	Purpose
FastMCP	MCP server framework
SQLite3	Lightweight persistent storage
uv	Ultra-fast Python package manager
Python 3.11+	Runtime

---

👤 Author

Talha — @talha963

---

📄 License

This project is licensed under the MIT License — feel free to use, modify, and distribute.

---

<div align="center"> _{Built with ❤️ using FastMCP — making AI tool integration effortless.} </div>