Expense Tracker MCP Server
Parasmani-yogi/Expense-Tracker-Local-MCP-Server
Gerencie despesas localmente via Claude com MCP e SQLite
Ver no GitHubServidor MCP local que permite gerenciar despesas pessoais através de linguagem natural com Claude. Armazena dados em SQLite com ferramentas para adicionar, listar, atualizar, deletar e resumir gastos por categoria.
Instalação
npx convez-ai Parasmani-yogi/Expense-Tracker-Local-MCP-Server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Registrar despesas pessoais conversando com Claude
- Acompanhar gastos por categoria e período
- Atualizar ou corrigir lançamentos existentes
- Gerar relatórios de gastos sem deixar dados em cloud
Veredito

MCP server bem estruturado para quem quer controlar despesas localmente via Claude. Simples de instalar e customizar, com armazenamento SQLite seguro, mas carece de recursos avançados como análise temporal ou exportação de relatórios.
README
A tradução para o português deste README ainda está na fila.
💸 Expense Tracker MCP Server
A lightweight Model Context Protocol (MCP) server built with FastMCP and SQLite that enables AI assistants such as Claude to manage personal expenses through natural language.
The server provides tools for adding, listing, updating, deleting, and summarizing expenses while storing all data locally in a SQLite database.
📚 Table of Contents
- 🔍 Overview
- ✨ Features
- 📁 Project Structure
- ⚙️ Requirements
- 🚀 Installation
- ▶️ Running the Server
- 🔎 FastMCP Inspector
- 🔌 Claude Desktop Integration
- 🛠️ Available Tools
- 📦 Available Resources
- 🏷️ Expense Categories
- 🗄️ Database Schema
- 💬 Example Claude Prompts
- 🧑💻 Development
🔍 Overview
Expense Tracker MCP Server exposes a set of MCP tools that allow AI assistants to interact directly with your expense data.
Instead of manually maintaining spreadsheets or expense apps, you can simply talk to Claude and ask it to:
- Record a new expense
- Update an incorrect entry
- Delete unwanted records
- Show expenses for a specific period
- Summarize spending by category
- View available categories and subcategories
All expense records are stored locally in SQLite, ensuring that your financial data remains under your control.
✨ Features
- Local-first SQLite storage
- FastMCP-powered MCP server
- Add new expenses with categories and notes
- View expenses within custom date ranges
- Generate category-wise spending summaries
- Update existing expense records
- Remove incorrect or duplicate entries
- Configurable categories via JSON
- Automatic category reload without restart
- Simple Python codebase for customization
- Compatible with Claude Desktop and other MCP clients
📁 Project Structure
expense-tracker-mcp/
├── main.py
├── expenses.db
├── categories.json
├── pyproject.toml
└── README.md
| File | Description |
|---|---|
main.py | MCP server implementation |
expenses.db | SQLite database |
categories.json | Expense categories and subcategories |
pyproject.toml | Project dependencies |
README.md | Project documentation |
⚙️ Requirements
| Requirement | Version |
|---|---|
| Python | 3.10+ |
| FastMCP | Latest |
| SQLite | Included with Python |
| uv | latest recommended |
🚀 Installation
Clone the Repository
git clone https://github.com/Parasmani-yogi/Expense-Tracker-Local-MCP-Server.git
cd Expense-Tracker-Local-MCP-Server
Install Dependencies
Using uv:
uv sync
Or using pip:
pip install fastmcp
▶️ Running the Server
Using uv:
uv run main.py
Using Python:
python main.py
The SQLite database is created automatically on first startup.
🔎 FastMCP Inspector
FastMCP includes a built-in Inspector that allows you to test MCP tools and resources directly from your browser.
Launch the Inspector:
uv run fastmcp dev inspector main.py
The Inspector can be used to:
- Test MCP tools interactively
- Inspect tool requests and responses
- View available resources
- Debug tool behavior
- Validate your server before connecting it to Claude Desktop
This is the recommended workflow during development.
🔌 Claude Desktop Integration
Add the following configuration to your claude_desktop_config.json file:
{
"mcpServers": {
"expense-tracker": {
"command": "uv",
"args": ["run", "main.py"],
"cwd": "/absolute/path/to/expense-tracker-mcp"
}
}
}
Restart Claude Desktop after updating the configuration.
🛠️ Available Tools
add_expense
Create a new expense record.
| Parameter | Type | Required |
|---|---|---|
| date | string | Yes |
| amount | float | Yes |
| category | string | Yes |
| subcategory | string | No |
| note | string | No |
Example
Add an expense - cab ride to dehli last sunday fare was 500Rs.
Request
{
"date": "2026-06-07",
"note": "Cab ride to Delhi",
"amount": "500",
"category": "Transport",
"subcategory": "Cab"
}
Response
{"status":"ok","id":1}
list_expenses
Retrieve all expenses within a specified date range.
| Parameter | Type | Required |
|---|---|---|
| start_date | string | Yes |
| end_date | string | Yes |
Example
Show my expenses of May.
Request
{
"end_date": "2026-03-31",
"start_date": "2026-03-01"
}
Response
[{"id":14,"date":"2026-03-12","amount":8500.0,"category":"Shopping","subcategory":"Electronics","note":"Laptop bag and accessories"},{"id":15,"date":"2026-03-22","amount":1500.0,"category":"Entertainment","subcategory":"Cinema","note":"Movie tickets + popcorn"},{"id":16,"date":"2026-03-08","amount":4200.0,"category":"Health","subcategory":"Fitness","note":"Gym membership - 3 months"}]
summarize
Generate category-wise spending totals.
| Parameter | Type | Required |
|---|---|---|
| start_date | string | Yes |
| end_date | string | Yes |
| category | string | No |
Example
Summarize my expenses for March 2026.
Request
{
"end_date": "2026-03-31",
"start_date": "2026-03-01"
}
Response
[{"category":"Entertainment","total_amount":1500.0},{"category":"Health","total_amount":4200.0},{"category":"Shopping","total_amount":8500.0}]
edit_expense
Update an existing expense record.
Only supplied fields are modified.
| Parameter | Type | Required |
|---|---|---|
| expense_id | integer | Yes |
| date | string | No |
| amount | float | No |
| category | string | No |
| subcategory | string | No |
| note | string | No |
Example
Update expense ID 15.
Change amount to 2000.
Request
{
"amount": 2000,
"expense_id": 15
}
Response
{"status":"ok","expense_id":15,"updated":{"date":"2026-03-22","amount":2000.0,"category":"Entertainment","subcategory":"Cinema","note":"Movie tickets + popcorn"}}
delete_expense
Delete an expense by ID.
| Parameter | Type | Required |
|---|---|---|
| expense_id | integer | Yes |
Example
Delete expense ID 25.
Request
{
"expense_id": 25
}
Response
{"status":"ok","deleted_expense_id":25}
📦 Available Resources
expense://categories
Returns all configured categories and subcategories from categories.json.
This resource is loaded fresh on every request, allowing you to modify categories without restarting the server.
Example
Show all available expense categories.
🏷️ Expense Categories
The server includes a structured category system designed to cover most personal and professional spending scenarios.
Each expense consists of:
- Category → High-level classification
- Subcategory → More specific spending type
Example
Category: food
Subcategory: groceries
Available Categories
| Category | Examples |
|---|---|
| food | groceries, dining_out, snacks |
| transport | fuel, cab_ride_hailing, tolls |
| housing | rent, furnishing, repairs |
| utilities | electricity, internet, mobile_phone |
| health | medicines, doctor_consultation |
| education | books, courses, workshops |
| entertainment | movies, games, streaming |
| shopping | clothing, electronics, accessories |
| subscriptions | SaaS, cloud services, newsletters |
| travel | flights, hotels, local_transport |
| business | hosting, ads, contractor_payments |
| investments | stocks, mutual_funds, crypto |
| personal_care | salon, cosmetics, hygiene |
| family_kids | school_fees, toys, events |
| gifts_donations | gifts, charity, festivals |
| finance_fees | brokerage, bank_charges |
| home | kitchenware, repairs, cleaning |
| pet | food, vet, grooming |
| taxes | income_tax, gst |
| misc | uncategorized, other |
Customizing Categories
All categories are defined in:
categories.json
You can:
- Add new categories
- Add new subcategories
- Rename existing entries
- Remove unused categories
Changes become available immediately without restarting the server.
🗄️ Database Schema
CREATE TABLE IF NOT EXISTS expenses (
id INTEGER PRIMARY KEY AUTOINCREMENT,
date TEXT NOT NULL,
amount REAL NOT NULL,
category TEXT NOT NULL,
subcategory TEXT DEFAULT '',
note TEXT DEFAULT ''
);
💬 Example Claude Prompts
Add Expense
I spent ₹450 on groceries today.
List Expenses
Show all expenses from 2026-06-01 to 2026-06-30.
Summarize Expenses
How much did I spend this month by category?
Update Expense
Update expense ID 3.
Change amount to ₹900 and note to "Weekly grocery shopping".
Delete Expense
Delete expense ID 3.
View Categories
What expense categories are available?
🧑💻 Development
Run the server locally:
uv run main.py
Database file:
expenses.db
Category configuration:
categories.json
The project is intentionally simple and easy to extend. New tools, resources, reports, analytics, and integrations can be added with minimal changes.