Advanced Expanse Tracker FastMCP Local
An AI-powered Expense & Budget Management MCP Server built using FastMCP, SQLite, and Python.
Ask AI about Advanced Expanse Tracker FastMCP Local
Powered by Claude Β· Grounded in docs
I know everything about Advanced Expanse Tracker FastMCP Local. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
AdvancedExpenseTracker (FastMCP)
An AI-powered Expense & Budget Management MCP Server built using FastMCP, SQLite, and Python.
This project exposes structured financial tools (expenses, income, budgets, recurring bills, analytics) that can be used by an LLM (like Claude Desktop or Cursor) as a personal financial advisor.
π Features Overview
- β Expense Tracking: Categories, subcategories, tags, notes, and payment methods.
- β Income & Cashflow: Log earnings and analyze net savings in real-time.
- β Recurring Engine: Auto-generate daily, weekly, monthly, or yearly bills.
- β Smart Budgeting: Set limits per category and get "Over Budget" warnings.
- β Search & Filtering: Find transactions by note, tag, or amount.
- β Metadata Management: Dynamic control over valid categories & payment methods.
- β Zero-Setup Database: SQLite database initializes automatically.
ποΈ Architecture
AdvancedExpenseTracker
β
βββ expenses.db # SQLite database (auto-created on first run)
βββ metadata.json # Categories & payment methods (auto-created)
βββ main.py # MCP server implementation
βββ README.md
π¦ Tech Stack
- Python 3.10+
- FastMCP (The only external dependency)
- SQLite (Built-in, serverless storage)
- uv (For ultra-fast dependency management)
βοΈ Installation (using uv)
This project is designed to run instantly with uv. You do not need to manually create virtual environments.
1οΈβ£ Install uv (if not installed)
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
2οΈβ£ Clone the Repository
git clone <your-repo-url>
cd AdvancedExpenseTracker
3οΈβ£ Test Run
You can verify the script works without installing anything globally:
uv run --with fastmcp main.py
On the first run, this will create expenses.db and metadata.json automatically.
π Configuration (Connect to AI)
To use this with Claude Desktop or Cursor, you need to tell them where the script is.
Option A: Claude Desktop App
- Open your config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Add the following (Replace
/ABSOLUTE/PATH/TO/with your real file path):
{
"mcpServers": {
"finance": {
"command": "uv",
"args": [
"run",
"--with",
"fastmcp",
"/ABSOLUTE/PATH/TO/main.py"
]
}
}
}
Option B: Cursor (IDE)
- Go to Cursor Settings > Features > MCP.
- Click + Add New MCP Server.
- Name:
Expense Tracker - Type:
command - Command:
uv run --with fastmcp /ABSOLUTE/PATH/TO/main.py
π§ MCP Capabilities (Detailed)
π Expense Management
β Add Expense
add_expense(
date="2026-01-05",
amount=250,
category="Food",
subcategory="Dining",
payment_method="Credit Card",
note="Dinner with friends",
tags="restaurant,weekend"
)
βοΈ Update Expense
Update only the fields you want to change:
update_expense(expense_id=1, amount=300, note="Updated bill amount")
β Delete Expense
delete_expense(expense_id=1)
π List Expenses
list_expenses(
start_date="2026-01-01",
end_date="2026-01-31",
category="Food",
limit=50
)
π Search Expenses
Search across category, subcategory, notes, and tags:
search_expenses(query="restaurant")
π° Income & Cashflow
β Add Income
add_income(
date="2026-01-01",
amount=5000,
source="Salary",
note="January Paycheck"
)
π Cashflow Analysis
get_cashflow(start_date="2026-01-01", end_date="2026-01-31")
Returns:
{
"total_income": 5000,
"total_expenses": 1800,
"net_savings": 3200,
"savings_rate": "64.0%"
}
π Recurring Expenses Engine
β Add Recurring Expense
add_recurring_expense(
name="Netflix",
amount=15.99,
category="Entertainment",
frequency="monthly",
start_date="2026-01-01"
)
Supported frequencies: daily, weekly, monthly, yearly.
π Process/Refresh Bills
Run this to generate actual expense entries from your templates:
process_recurring_expenses(target_date="2026-03-31")
π Budgeting & Alerts
π― Set Monthly Budget
set_monthly_budget(category="Food", amount=500)
π Budget Report
get_budget_report(month_str="2026-01")
Status logic:
- β OK
- β οΈ WARNING (>90% used)
- β OVER BUDGET
π§Ύ Metadata Management
π₯ Get Metadata (Resource)
The AI reads this to know which categories are allowed.
expense://metadata
β Manage Categories/Methods
manage_metadata(action="add", type="categories", value="Education")
manage_metadata(action="remove", type="payment_methods", value="Cash")
π€ Built-in LLM Prompt
π§ Financial Advisor Prompt
financial_advisor()
This prompt instructs the LLM to:
- Act as a data-driven financial advisor.
- Always validate metadata before logging.
- Prioritize cashflow health and budget warnings.
- Proactively manage recurring subscriptions.
π Data Safety
- All data is stored locally in
expenses.db. - No external API calls or cloud syncing.
- To backup your data, simply copy the
.dbfile.
π License
MIT License β free to use, modify, and distribute.
π Author
Anubhab Das
