1. Conduid
  2. Finance
  3. io.github.justfsl50/expense-mcp
MCP server · Finance

io.github.justfsl50/expense-mcp

· github.com/justfsl50/expense-mcp

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

Unclaimed finance
InstallView source
37Low

Scored 6 months ago · breakdown

About io.github.justfsl50/expense-mcp

io.github.justfsl50/expense-mcp is an MCP server in the Finance category: personal Expense Tracker MCP Server — expenses, income, budgets & savings goals.

Install

uvx
uvx expense-mcp
pip
pip install expense-mcp

This server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.

Tools (10)

budget_listView budgets with usage %

Parameters not published.

budget_setSet monthly category budget

Parameters not published.

expense_addSave expense or income

Parameters not published.

expense_deleteDelete with Pydantic confirmation prompt

Parameters not published.

expense_insightsSpending patterns and top categories

Parameters not published.

expense_searchFilter by text, date, category, amount

Parameters not published.

expense_summarytoday / week / month / year totals

Parameters not published.

goal_createCreate savings goal

Parameters not published.

goal_listView goals with progress bars

Parameters not published.

goal_updateAdd money toward goal

Parameters not published.

Ask AI

✦

Ask AI about io.github.justfsl50/expense-mcp

Powered by Claude · Grounded in docs

I know everything about io.github.justfsl50/expense-mcp. Ask me about installation, configuration, usage, or troubleshooting.

Security checks

  • ✓README presentThe repository ships documentation.

5 checks have not been run yet.

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

# with uv (recommended)
uv pip install git+https://github.com/justfsl50/expense-mcp.git

# with pip
pip install git+https://github.com/justfsl50/expense-mcp.git

# from source
git clone https://github.com/justfsl50/expense-mcp.git
cd expense-mcp
pip 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):

{
  "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

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

HTTP mode (remote / multi-client)

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

Environment Variables

Variable Default Description
DATABASE_URL sqlite:///expenses.db SQLite or PostgreSQL URL
CURRENCY ₹ Currency symbol
DEFAULT_USER default User ID for multi-user setups

PostgreSQL example:

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

Tools

Tool Description Read-only
expense_add Save expense or income ❌
expense_search Filter by text, date, category, amount ✅
expense_summary today / week / month / year totals ✅
expense_delete Delete with Pydantic confirmation prompt ❌
expense_insights Spending patterns and top categories ✅
budget_set Set monthly category budget ❌
budget_list View budgets with usage % ✅
goal_create Create savings goal ❌
goal_update Add money toward goal ❌
goal_list View goals with progress bars ✅

Resources

URI Description
expense://summary/month Current month summary
expense://budgets/current This month's budgets
expense://goals/all All savings goals

Prompts

Prompt Title Description
monthly_review Monthly Review Start a full month spending review
budget_setup Budget Setup Auto-suggest budgets from history
savings_plan Savings Plan Create 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_at
budgets   — id, user_id, category, amount, month
goals     — id, user_id, name, target, saved, deadline

License

MIT — free to use, modify, and distribute.

README copy captured when this server was indexed; it may lag the repository. The original is authoritative.

Questions

About io.github.justfsl50/expense-mcp

How do I install io.github.justfsl50/expense-mcp?

Run uvx expense-mcp, then add the server to your MCP client's configuration.

Is io.github.justfsl50/expense-mcp safe to use with an AI agent?

Its trust score is 37 out of 100 (low). It passes 1 of the 1 static security checks run so far. It has no ConduID identity yet, so agent calls to it are not receipted.

Is io.github.justfsl50/expense-mcp still maintained?

Conduid hasn't recorded a commit date for this repository yet. Check the repository directly for recent activity.