Expense Mcp

io.github.justfsl50Published by GitHub account justfsl50v1.0.1Updated Oct 24, 2026

Personal Expense Tracker MCP Server — expenses, income, budgets & savings goals

VerifiedSTDIODesktop onlyProductivity & WorkflowFinance

Overview

AI-generated overview

Lets an assistant record personal expenses and income, track budgets and savings goals, and produce spending summaries and insights.

What you can do
Provides tools to add expenses or income with categories and descriptions, search and filter records, and summarize spending by day, week, month, or year. It also manages per-category monthly budgets with usage alerts, creates and updates savings goals, and reports spending patterns such as top categories and daily averages. Deletion is confirmed through an elicitation prompt, and summary, budget, and goal data are exposed as resources.
When to use it
Useful for personal finance tracking through natural conversation in an MCP client, for example logging a purchase, checking whether a category is within budget, or reviewing a month of spending. It suits a single user or a small multi-user setup backed by a local or self-hosted database.
Requirements
Runs locally as a Python package (expense-mcp) over stdio, or in an HTTP mode on a local address. Needs a Python environment and a database URL via DATABASE_URL (SQLite by default, PostgreSQL supported); CURRENCY and DEFAULT_USER are optional settings. No authentication is declared.
Before you install
It writes to and deletes from your expense database, so point DATABASE_URL at a database you are willing to modify and keep backups. A PostgreSQL URL may embed credentials; store it in the client configuration rather than sharing it. Deletion is confirmed by a prompt but still removes records.

Installation

In SourceWeft

  1. Open Expense Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

💰 expense-mcp

Personal Expense Tracker as an MCP Server — works with Claude Desktop, Cursor, nanobot, Windsurf, and any MCP-compatible client.

[Python] [MCP SDK] [License]

Features

  • 📝 Track expenses & income with categories and descriptions
  • 📊 Spending summaries — today, week, month, year
  • 💳 Budget management — set limits per category, get alerts at 80%/100%
  • 🎯 Savings goals — create goals, track progress with visual bars
  • 📈 Spending insights — top categories, daily averages, biggest days
  • 🗑️ Safe deletion — Pydantic-based elicitation for confirmation
  • 🔄 Dual transport — stdio (local) + streamable HTTP (remote)

Install

bash
# with uv (recommended)uv pip install git+https://github.com/justfsl50/expense-mcp.git
# with pippip install git+https://github.com/justfsl50/expense-mcp.git
# from sourcegit clone https://github.com/justfsl50/expense-mcp.gitcd expense-mcppip install -e .

Quick Start

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (Mac):

json
{  "mcpServers": {    "expense-mcp": {      "command": "uv",      "args": ["run", "expense-mcp"],      "env": {        "DATABASE_URL": "sqlite:///expenses.db",        "CURRENCY": "₹",        "DEFAULT_USER": "me"      }    }  }}

Cursor / Windsurf

Same config — paste into MCP settings under the respective app.

nanobot

json
{  "mcp": {    "servers": [{      "name": "expense-mcp",      "command": "uv run expense-mcp"    }]  }}

HTTP mode (remote / multi-client)

bash
python server.py http# Server runs at http://127.0.0.1:8000/mcp

Environment Variables

VariableDefaultDescription
DATABASE_URLsqlite:///expenses.dbSQLite or PostgreSQL URL
CURRENCY₹Currency symbol
DEFAULT_USERdefaultUser ID for multi-user setups

PostgreSQL example:

DATABASE_URL=postgresql://user:pass@localhost:5432/expenses

Tools

ToolDescriptionRead-only
expense_addSave expense or income❌
expense_searchFilter by text, date, category, amount✅
expense_summarytoday / week / month / year totals✅
expense_deleteDelete with Pydantic confirmation prompt❌
expense_insightsSpending patterns and top categories✅
budget_setSet monthly category budget❌
budget_listView budgets with usage %✅
goal_createCreate savings goal❌
goal_updateAdd money toward goal❌
goal_listView goals with progress bars✅

Resources

URIDescription
expense://summary/monthCurrent month summary
expense://budgets/currentThis month's budgets
expense://goals/allAll savings goals

Prompts

PromptTitleDescription
monthly_reviewMonthly ReviewStart a full month spending review
budget_setupBudget SetupAuto-suggest budgets from history
savings_planSavings PlanCreate a plan for a savings goal

Usage Examples

Just talk naturally in any MCP client:

"spent 500 on groceries""show food expenses this week""how much did I spend last month?""set food budget to 5000""am I within budget?""save 1000 toward my iPhone goal""give me spending insights""delete expense #12"

Architecture

  • MCP SDK v1.26.0 with FastMCP + json_response=True
  • Typed lifespan — DB engine managed via AppContext dataclass
  • SQLAlchemy 2.0 — DeclarativeBase, sessionmaker
  • Pydantic v2 — input validation, elicitation schemas
  • Tool annotations — readOnlyHint, destructiveHint, idempotentHint
  • Context logging — ctx.info(), ctx.warning() in tools

Database Schema

expenses  — id, user_id, amount, category, description, type, date, source, created_atbudgets   — id, user_id, category, amount, monthgoals     — id, user_id, name, target, saved, deadline

License

MIT — free to use, modify, and distribute.

Source: README.md at commit 6538644

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts