English Français العربية

io.github.justfsl50/expense-mcp

Registre officiel Autres

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

Code source Documentation

Que pouvez-vous faire avec io.github.justfsl50/expense-mcp ?

  • 📝 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)

Installation

Ajoutez ceci à la configuration MCP de votre client (Claude Desktop : claude_desktop_config.json ; Cursor : .cursor/mcp.json ; VS Code et les autres utilisent la même forme « mcpServers »).

PYPI package expense-mcp
Claude Code 
claude mcp add expense-mcp -e 'DATABASE_URL=<DATABASE_URL>' -e 'CURRENCY=<CURRENCY>' -e 'DEFAULT_USER=<DEFAULT_USER>' -- uvx expense-mcp==1.0.1
Configuration JSON (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "expense-mcp": {
            "command": "uvx",
            "args": [
                "expense-mcp==1.0.1"
            ],
            "env": {
                "DATABASE_URL": "<DATABASE_URL>",
                "CURRENCY": "<CURRENCY>",
                "DEFAULT_USER": "<DEFAULT_USER>"
            }
        }
    }
}

Variables d'environnement

  • DATABASE_URL SQLite or PostgreSQL database URL
  • CURRENCY Currency symbol (default: ₹)
  • DEFAULT_USER User ID for multi-user setups

Documentation

Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.

Sommaire
  1. 💰 expense-mcp
  2. Features
  3. Install
  4. Quick Start
  5. Environment Variables
  6. Tools
  7. Resources
  8. Prompts
  9. Usage Examples
  10. Architecture
  11. License

💰 expense-mcp

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

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

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_at
budgets   — id, user_id, category, amount, month
goals     — id, user_id, name, target, saved, deadline

License

MIT — free to use, modify, and distribute.

Questions fréquentes

Qu'est-ce que io.github.justfsl50/expense-mcp ?

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

Comment installer io.github.justfsl50/expense-mcp ?

Il s'exécute sur votre machine. Dans Claude Code : claude mcp add expense-mcp -e 'DATABASE_URL=<DATABASE_URL>' -e 'CURRENCY=<CURRENCY>' -e 'DEFAULT_USER=<DEFAULT_USER>' -- uvx expense-mcp==1.0.1. Pour les autres clients, collez la configuration JSON de cette page dans leurs réglages MCP.

Faut-il une clé API pour io.github.justfsl50/expense-mcp ?

Son entrée au registre n'indique aucune clé ni secret obligatoire. Certaines fonctions peuvent tout de même demander un compte auprès du service auquel il se connecte.

io.github.justfsl50/expense-mcp est-il open source ?

Oui. Son code est sur GitHub sous licence MIT.

Qui maintient io.github.justfsl50/expense-mcp ?

Il est publié par justfsl50. AI.tn le référence sans le maintenir ni le recommander.

Issu du registre MCP officiel. Être listé n'est pas une recommandation : vérifiez le code et les permissions d'un serveur avant de lui donner accès à vos données.