Expense Tracker MCP Server
README.md
# 💰 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
```text
┌──────────────────────┐
│ 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
```text
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:
```bash
uv --version
```
You should see the installed version of `uv`.
---
# 📁 2. Create the Project
Create a folder for the project:
```bash
mkdir expense-tracker
cd expense-tracker
```
Open it in VS Code:
```bash
code .
```
---
# 🐍 3. Initialize the Python Project
Run:
```bash
uv init
```
This creates the Python project configuration.
---
# 📦 4. Install FastMCP
Install FastMCP using:
```bash
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:
```text
expenses
│
├── id
├── date
├── amount
├── category
├── subcategory
├── note
├── payment_method
├── currency
└── created_at
```
Example record:
```text
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:
```python
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:
```text
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:
```text
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:
```text
Total spending
Number of transactions
Average expense
Category breakdown
Largest expense
```
Example:
```text
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:
```python
@mcp.resource(
"expenses://categories",
mime_type="application/json"
)
def expense_categories():
return """
{
"categories": [
"Food",
"Transport",
"Shopping",
"Bills",
"Entertainment"
]
}
"""
```
The important difference is:
```text
Tool → Performs an action
Resource → Provides information
Prompt → Provides a reusable instruction/template
```
---
# ▶️ 9. Run the Server
You can run the server using:
```bash
uv run python server.py
```
The MCP server will start locally.
---
# 🔍 10. Inspect/Test the MCP Server
FastMCP provides development tooling.
You can use:
```bash
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:
```json
{
"mcpServers": {
"expense-tracker": {
"command": "/path/to/uv",
"args": [
"run",
"--directory",
"/path/to/expense-tracker",
"python",
"server.py"
]
}
}
}
```
Replace:
```text
/path/to/uv
```
with the actual path to your `uv` executable.
On Linux, find it using:
```bash
which uv
```
Also replace:
```text
/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:
```bash
uv run python server.py
```
### Step 2
Check the `uv` path:
```bash
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:
```text
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
```text
I spent ₹250 on dinner today.
```
Claude can use:
```text
add_expense()
```
---
### Check total spending
```text
How much have I spent so far?
```
Claude can use:
```text
get_total_expenses()
```
---
### Get a summary
```text
Give me a summary of all my expenses.
```
Claude can use:
```text
get_expense_summary()
```
---
### Search
```text
Show me all my shopping expenses.
```
Claude can use:
```text
search_expenses()
```
---
### Find largest expenses
```text
What are my five biggest expenses?
```
Claude can use:
```text
get_top_expenses()
```
---
### Monthly analysis
```text
How much did I spend in August 2026?
```
Claude can use:
```text
get_monthly_summary()
```
---
### Date range
```text
Show me everything I spent between August 1 and August 15.
```
Claude can use:
```text
get_expenses_by_date_range()
```
---
### Update an expense
```text
Change expense 12 from ₹300 to ₹450.
```
Claude can use:
```text
update_expense()
```
---
### Delete an expense
```text
Delete expense number 12.
```
Claude can use:
```text
delete_expense()
```
---
# 🔄 14. Complete Request Flow
When you say:
> "I spent ₹500 on dinner today."
The flow is:
```text
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:
```text
User → Application → Database
```
With MCP:
```text
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:
```text
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
```text
I spent ₹300 on lunch today.
```
### AI
```text
Expense added successfully.
```
---
### User
```text
I also spent ₹120 on an auto.
```
### AI
```text
Expense added successfully.
```
---
### User
```text
How much did I spend today?
```
### AI
```text
You spent ₹420 today.
```
---
### User
```text
Give me my complete expense summary.
```
### AI
```text
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
```text
set_budget()
get_budget_status()
```
Example:
> My monthly budget is ₹20,000.
---
### Spending Insights
```text
get_spending_insights()
```
Example:
> Where am I overspending?
---
### Monthly Comparison
```text
compare_months()
```
Example:
> Did I spend more this month than last month?
---
### Recurring Expenses
```text
add_recurring_expense()
get_recurring_expenses()
```
---
### Export
Add support for:
```text
CSV
JSON
Excel
PDF
```
---
### Visualization
Generate:
```text
Monthly spending charts
Category charts
Spending trends
```
---
### AI Financial Assistant
Eventually, the MCP server can become the backend for an AI financial assistant:
```text
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:
```text
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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues