💰 Expense Tracker Remote MCP Server

A simple Model Context Protocol (MCP) server built with Python and FastMCP that provides tools for managing and analyzing personal expenses through an SQLite database.

The server supports adding expenses, retrieving expenses within a date range, summarizing expenses by category, and accessing available expense categories as an MCP resource.

🚀 Features

• ➕ Add new expense records

• 📋 List expenses within a specific date range

• 📊 Summarize expenses by category

• 🗂️ Expose expense categories through an MCP resource

• 💾 Persistent storage using SQLite

• 🌐 Runs as a remote/HTTP MCP server

• 🔌 Compatible with MCP clients and MCP Inspector

• ⚡ Built with FastMCP

Related MCP server: expense-mcp

🛠️ Tech Stack

• Python

• FastMCP

• Model Context Protocol (MCP)

• SQLite

• uv – Python package/project manager

• JSON

📁 Project Structure

Expense_Tracker_Remote_MCP_Server/
│
├── src/
│   └── test_remote_mcp_server/
│       └── __init__.py
│
├── categories.json
├── expenses.db
├── main.py
├── pyproject.toml
├── uv.lock
├── .gitignore
└── README.md

Important Files

⚙️ How It Works

The MCP server uses FastMCP to expose expense-management functionality as MCP tools.

                    MCP Client
                        │
                        ▼
                FastMCP MCP Server
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
    add_expense    list_expenses   summarize
          │             │             │
          └─────────────┼─────────────┘
                        ▼
                   SQLite DB
                  expenses.db

The server also exposes:

expense://categories

as an MCP resource for retrieving available expense categories.

🔧 MCP Tools

1. add_expense

Adds a new expense to the SQLite database.

Parameters

Example

add_expense(
    date="2026-08-29",
    amount=250,
    category="Food",
    subcategory="Lunch",
    note="Lunch at college"
)

Example response:

{
  "status": "ok",
  "id": 1
}

📋 2. list_expenses

Returns expense records within an inclusive date range.

Parameters

Example

list_expenses(
    start_date="2026-08-01",
    end_date="2026-08-29"
)

Example response:

[
  {
    "id": 1,
    "date": "2026-08-29",
    "amount": 250,
    "category": "Food",
    "subcategory": "Lunch",
    "note": "Lunch at college"
  }
]

📊 3. summarize

Summarizes expenses by category within an inclusive date range.

An optional category can be provided to filter the results.

Parameters

Example

summarize(
    start_date="2026-08-01",
    end_date="2026-08-29"
)

Example response:

[
  {
    "category": "Food",
    "total_amount": 2500
  },
  {
    "category": "Transport",
    "total_amount": 1200
  }
]

You can also filter by category:

summarize(
    start_date="2026-08-01",
    end_date="2026-08-29",
    category="Food"
)

🗂️ MCP Resource

The server exposes the following resource:

expense://categories

This resource reads the contents of:

categories.json

The file is read each time the resource is requested, meaning category changes can be reflected without restarting the server.

💾 Database

The server uses SQLite for persistent expense storage.

The database contains the following table:

expenses

with the following columns:

The database table is automatically created when the server starts if it does not already exist.

🧰 Installation

Prerequisites

Make sure you have:

• Python 3.10+

• uv

• Git

1. Clone the repository

git clone https://github.com/abhisek0407/Expense_Tracker_Remote_MCP_Server.git
cd Expense_Tracker_Remote_MCP_Server

2. Install dependencies

If the project already contains pyproject.toml and uv.lock:

uv sync

▶️ Run the MCP Server

The server is configured to run using Streamable HTTP on port 8000.

Start the server with:

uv run python main.py

The server will listen on:

http://localhost:8000

The MCP endpoint is:

http://localhost:8000/mcp

🔍 Test With MCP Inspector

You can test the server locally using MCP Inspector.

In another terminal:

uv run fastmcp dev inspector main.py

Then configure the Inspector with:

• Transport Type: Streamable HTTP

• URL: http://localhost:8000/mcp

• Connection Type: Via Proxy Click Connect.

Once connected, the Inspector should expose:

Tools

• add_expense

• list_expenses

• summarize Resource

• expense://categories

🌐 Remote Deployment

This project can be deployed as a remote MCP server using a platform such as FastMCP Cloud.

The server uses:

mcp.run(
    transport="http",
    host="0.0.0.0",
    port=8000
)

This allows the MCP server to accept HTTP connections instead of only operating through STDIO.

After deployment, the MCP server can be accessed through the remote endpoint provided by the hosting platform.

For example:

https://your-server.fastmcp.app/mcp

The actual URL depends on the server name and deployment configuration.

🔐 Environment Variables

Currently, the server does not require any external API keys or authentication credentials.

If authentication or external services are added in the future, environment variables can be configured through the deployment platform.

🧪 Example Workflow

A typical interaction with the MCP server can look like:

User
 │
 │ "Add ₹500 spent on food today"
 ▼
MCP Client
 │
 │ add_expense()
 ▼
Expense Tracker MCP Server
 │
 ▼
SQLite Database
 │
 │ Expense stored
 ▼
MCP Response
 │
 ▼
MCP Client

For analysis:

User
 │
 │ "How much did I spend by category this month?"
 ▼
MCP Client
 │
 │ summarize()
 ▼
Expense Tracker MCP Server
 │
 ▼
SQLite
 │
 │ GROUP BY category
 ▼
Category-wise totals

📌 Current Limitations

• No authentication mechanism is currently implemented.

• The server currently uses a local SQLite database.

• No user/account separation is implemented.

• Date values are stored as text and should follow a consistent date format such as YYYY-MM-DD.

• Categories are loaded from a local categories.json file.

🚧 Future Improvements

Possible improvements include:

• 🔐 Authentication and authorization

• 👤 Multiple user support

• ☁️ Cloud database integration

• 📈 Advanced expense analytics

• 💰 Budget tracking

• 🔔 Budget alerts

• 📅 Monthly and yearly reports

• 📊 Spending visualization

• 🏷️ Custom categories

• 🤖 AI-powered spending insights

• 🧾 Receipt processing

• 💱 Multi-currency support

🎯 Purpose of the Project

This project was created to learn and demonstrate the implementation of an MCP server using FastMCP, including:

• MCP tools

• MCP resources

• SQLite integration

• HTTP/Streamable HTTP transport

• Local MCP server testing

• MCP Inspector

• Remote MCP server deployment It serves as a practical example of connecting an AI/MCP client with a persistent backend application.

📄 License

This project is available for educational and personal use.