💰 Expense Tracker MCP Server

A local Expense Tracker MCP Server built with Python, FastMCP, and SQLite.

This project allows an MCP-compatible AI client such as Claude Desktop to interact with a local expense database using natural language.

For example:

"Add ₹500 for dinner today."

"How much have I spent?"

"Give me a summary of my expenses."

"Show me my biggest expenses."

The AI client communicates with the FastMCP server, which executes the appropriate tools and interacts with the local SQLite database.

---

📌 Project Overview

Architecture

                ┌──────────────────────┐
                │     MCP Client       │
                │    Claude Desktop    │
                └──────────┬───────────┘
                           │
                           │ MCP Protocol
                           ▼
                ┌──────────────────────┐
                │   Expense Tracker    │
                │      MCP Server      │
                │       FastMCP        │
                └──────────┬───────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
           MCP Tools   MCP Resources  Prompts
              │
              ▼
        ┌───────────────┐
        │    SQLite     │
        │  expenses.db  │
        └───────────────┘

---

🛠️ Technologies Used

• Python
• FastMCP
• SQLite
• uv
• Claude Desktop
• MCP (Model Context Protocol)

---

📂 Project Structure

expense-tracker/
│
├── server.py
├── expenses.db
├── pyproject.toml
├── .python-version
├── README.md
└── .gitignore

server.py

Contains the MCP server, database initialization, and MCP tools.

expenses.db

Local SQLite database containing all expense records.

pyproject.toml

Contains project metadata and dependencies.

README.md

Project documentation.

---

🚀 Installation

1. Install uv

Install uv if it is not already installed.

Verify the installation:

uv --version

You should see the installed version of uv.

---

📁 2. Create the Project

Create a folder for the project:

mkdir expense-tracker
cd expense-tracker

Open it in VS Code:

code .

---

🐍 3. Initialize the Python Project

Run:

uv init

This creates the Python project configuration.

---

📦 4. Install FastMCP

Install FastMCP using:

uv add fastmcp

FastMCP is used to create and expose the MCP server and its tools.

---

🗄️ 5. SQLite Database

This project uses SQLite because the expense tracker is designed to run locally.

The database is automatically created when the server starts.

The database contains an expenses table.

Example structure:

expenses
│
├── id
├── date
├── amount
├── category
├── subcategory
├── note
├── payment_method
├── currency
└── created_at

Example record:

ID:             1
Date:           2026-08-22
Amount:         500
Category:       Food
Subcategory:    Dinner
Note:           Dinner with friends
Payment Method: UPI
Currency:       INR

---

🧠 6. MCP Server

The MCP server is created using FastMCP.

Basic structure:

from fastmcp import FastMCP

mcp = FastMCP("Expense Tracker")

The server acts as the bridge between the AI client and the local expense database.

---

🔧 7. MCP Tools

The server exposes several tools that the AI can call.

add_expense

Adds a new expense.

Example request:

Add ₹500 for dinner today.

The AI can call:

add_expense(
    amount=500,
    category="Food",
    subcategory="Dinner"
)

---

get_expense

Retrieves a specific expense using its ID.

Example:

Show me expense number 5.

---

list_expenses

Returns recent expenses.

Example:

Show me my recent expenses.

---

update_expense

Updates an existing expense.

Example:

Change expense 5 from ₹500 to ₹650.

---

delete_expense

Deletes an expense.

Example:

Delete expense number 5.

---

search_expenses

Searches expenses using category, subcategory, note, or payment method.

Example:

Find all my food expenses.

---

get_total_expenses

Calculates the total amount spent.

Example:

How much have I spent in total?

---

get_category_summary

Groups expenses by category.

Example:

How much did I spend on food, transport and shopping?

Example result:

Food        ₹5,200
Shopping    ₹3,400
Transport   ₹2,100
Bills       ₹1,750

---

get_monthly_summary

Returns spending information for a specific month.

Example:

How much did I spend in August 2026?

---

get_expenses_by_date_range

Returns expenses between two dates.

Example:

Show my expenses from August 1 to August 15.

---

get_top_expenses

Returns the largest expenses.

Example:

What are my five biggest expenses?

---

get_expense_summary

Provides an overall financial summary.

It can include:

Total spending
Number of transactions
Average expense
Category breakdown
Largest expense

Example:

Total Spent: ₹12,450
Transactions: 32
Average Expense: ₹389

Top Categories:

Food        ₹4,500
Shopping    ₹3,200
Transport   ₹2,100
Bills       ₹1,800

Largest Expense:

₹2,500
Category: Shopping

---

📚 8. MCP Resources

MCP resources are used to expose information/context to the MCP client.

For example:

@mcp.resource(
    "expenses://categories",
    mime_type="application/json"
)
def expense_categories():
    return """
    {
        "categories": [
            "Food",
            "Transport",
            "Shopping",
            "Bills",
            "Entertainment"
        ]
    }
    """

The important difference is:

Tool      → Performs an action

Resource  → Provides information

Prompt    → Provides a reusable instruction/template

---

▶️ 9. Run the Server

You can run the server using:

uv run python server.py

The MCP server will start locally.

---

🔍 10. Inspect/Test the MCP Server

FastMCP provides development tooling.

You can use:

uv run fastmcp dev server.py

This is useful for testing and inspecting the MCP server during development.

---

🤖 11. Connect to Claude Desktop

To use the expense tracker through Claude Desktop, add the MCP server to the Claude Desktop configuration.

The configuration generally looks like:

{
  "mcpServers": {
    "expense-tracker": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/expense-tracker",
        "python",
        "server.py"
      ]
    }
  }
}

Replace:

/path/to/uv

with the actual path to your uv executable.

On Linux, find it using:

which uv

Also replace:

/path/to/expense-tracker

with the actual project directory.

---

⚠️ 12. If Claude Desktop Shows a Connection Error

If Claude cannot connect to the MCP server:

Step 1

Check that the server works independently:

uv run python server.py

Step 2

Check the uv path:

which uv

Step 3

Make sure the Claude configuration uses the correct absolute path.

Step 4

Restart Claude Desktop after changing the configuration.

Step 5

Check:

Claude Desktop
    ↓
Settings
    ↓
Developer
    ↓
Configuration

Then verify the MCP server configuration.

---

💬 13. How to Use the Expense Tracker

Once the MCP server is connected to Claude, you don't need to manually call the functions.

You can simply use natural language.

Add an expense

I spent ₹250 on dinner today.

Claude can use:

add_expense()

---

Check total spending

How much have I spent so far?

Claude can use:

get_total_expenses()

---

Get a summary

Give me a summary of all my expenses.

Claude can use:

get_expense_summary()

---

Search

Show me all my shopping expenses.

Claude can use:

search_expenses()

---

Find largest expenses

What are my five biggest expenses?

Claude can use:

get_top_expenses()

---

Monthly analysis

How much did I spend in August 2026?

Claude can use:

get_monthly_summary()

---

Date range

Show me everything I spent between August 1 and August 15.

Claude can use:

get_expenses_by_date_range()

---

Update an expense

Change expense 12 from ₹300 to ₹450.

Claude can use:

update_expense()

---

Delete an expense

Delete expense number 12.

Claude can use:

delete_expense()

---

🔄 14. Complete Request Flow

When you say:

"I spent ₹500 on dinner today."

The flow is:

You
 │
 ▼
Claude Desktop
 │
 │ Understands request
 ▼
MCP Client
 │
 │ Calls tool
 ▼
add_expense()
 │
 ▼
FastMCP Server
 │
 ▼
SQLite
 │
 ▼
expenses.db
 │
 ▼
Success Response
 │
 ▼
Claude
 │
 ▼
"Expense added successfully."

---

🧩 15. Why MCP Is Useful Here

Without MCP:

User → Application → Database

With MCP:

User
  ↓
AI
  ↓
MCP
  ↓
Expense Tools
  ↓
Database

The AI can decide which tool is appropriate based on the user's natural-language request.

This makes the expense tracker a good example of AI + tools + local data.

---

🔐 16. Local Data and Privacy

This project stores expense data locally in:

expenses.db

The database is not inherently hosted on a cloud server.

This makes the project useful for experimenting with personal/local financial data.

However, when using an external AI client, prompts and tool results may still be processed according to that client's policies. Avoid assuming that "local MCP server" means every piece of data stays entirely on your machine.

---

🧪 17. Example Session

User

I spent ₹300 on lunch today.

AI

Expense added successfully.

---

User

I also spent ₹120 on an auto.

AI

Expense added successfully.

---

User

How much did I spend today?

AI

You spent ₹420 today.

---

User

Give me my complete expense summary.

AI

Total Spending: ₹420

Transactions: 2

Average Expense: ₹210

Categories:

Food: ₹300
Transport: ₹120

Largest Expense:

Lunch — ₹300

---

🎯 18. What I Learned From This Project

This project demonstrates knowledge of:

• Python
• SQLite
• Database CRUD operations
• FastMCP
• MCP tools
• MCP resources
• MCP client/server architecture
• Tool calling
• Natural-language interaction with databases
• Local AI integrations
• JSON-based configuration
• uv project management

---

🚀 19. Future Improvements

The project can be extended with:

Budget Management

set_budget()
get_budget_status()

Example:

My monthly budget is ₹20,000.

---

Spending Insights

get_spending_insights()

Example:

Where am I overspending?

---

Monthly Comparison

compare_months()

Example:

Did I spend more this month than last month?

---

Recurring Expenses

add_recurring_expense()
get_recurring_expenses()

---

Export

Add support for:

CSV
JSON
Excel
PDF

---

Visualization

Generate:

Monthly spending charts
Category charts
Spending trends

---

AI Financial Assistant

Eventually, the MCP server can become the backend for an AI financial assistant:

                    AI Expense Assistant
                            │
                            ▼
                     MCP Server
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
       Expenses           Budget          Analytics
          │                 │                 │
          └─────────────────┼─────────────────┘
                            ▼
                         SQLite

The user could ask:

"Analyze my spending this month and tell me three areas where I can reduce expenses."

The AI could retrieve the required data through MCP tools and generate an analysis.

---

✅ Final Workflow

The complete development workflow is:

1. Install uv
       ↓
2. Create project folder
       ↓
3. Open in VS Code
       ↓
4. uv init
       ↓
5. uv add fastmcp
       ↓
6. Create server.py
       ↓
7. Initialize SQLite
       ↓
8. Create MCP tools
       ↓
9. Create MCP resources
       ↓
10. Run server
       ↓
11. Test/inspect with FastMCP
       ↓
12. Configure Claude Desktop
       ↓
13. Restart Claude
       ↓
14. Use natural language
       ↓
15. Claude calls MCP tools
       ↓
16. Tools interact with SQLite
       ↓
17. Results return to Claude

🏆 Project Summary

Expense Tracker MCP Server is a local AI-enabled expense management system that uses FastMCP to expose expense-management tools and resources, with SQLite as the local persistence layer and an MCP-compatible client such as Claude Desktop as the natural-language interface.

It demonstrates how an AI application can safely interact with structured local data through the Model Context Protocol (MCP) instead of directly accessing the database.