{
  "markdown": "# 💰 expense-mcp\n\n> Personal Expense Tracker as an MCP Server — works with Claude Desktop, Cursor, nanobot, Windsurf, and any MCP-compatible client.\n\n[![Python](https://img.shields.io/badge/python-≥3.12-blue)](https://python.org)\n[![MCP SDK](https://img.shields.io/badge/MCP_SDK-1.26.0-green)](https://github.com/modelcontextprotocol/python-sdk)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n<!-- mcp-name: io.github.justfsl50/expense-mcp -->\n---\n\n## Features\n\n- 📝 **Track expenses & income** with categories and descriptions\n- 📊 **Spending summaries** — today, week, month, year\n- 💳 **Budget management** — set limits per category, get alerts at 80%/100%\n- 🎯 **Savings goals** — create goals, track progress with visual bars\n- 📈 **Spending insights** — top categories, daily averages, biggest days\n- 🗑️ **Safe deletion** — Pydantic-based elicitation for confirmation\n- 🔄 **Dual transport** — stdio (local) + streamable HTTP (remote)\n\n---\n\n## Install\n\n```bash\n# with uv (recommended)\nuv pip install git+https://github.com/justfsl50/expense-mcp.git\n\n# with pip\npip install git+https://github.com/justfsl50/expense-mcp.git\n\n# from source\ngit clone https://github.com/justfsl50/expense-mcp.git\ncd expense-mcp\npip install -e .\n```\n\n---\n\n## Quick Start\n\n### Claude Desktop\n\nAdd to `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac):\n\n```json\n{\n  \"mcpServers\": {\n    \"expense-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"expense-mcp\"],\n      \"env\": {\n        \"DATABASE_URL\": \"sqlite:///expenses.db\",\n        \"CURRENCY\": \"₹\",\n        \"DEFAULT_USER\": \"me\"\n      }\n    }\n  }\n}\n```\n\n### Cursor / Windsurf\n\nSame config — paste into MCP settings under the respective app.\n\n### nanobot\n\n```json\n{\n  \"mcp\": {\n    \"servers\": [{\n      \"name\": \"expense-mcp\",\n      \"command\": \"uv run expense-mcp\"\n    }]\n  }\n}\n```\n\n### HTTP mode (remote / multi-client)\n\n```bash\npython server.py http\n# Server runs at http://127.0.0.1:8000/mcp\n```\n\n---\n\n## Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `DATABASE_URL` | `sqlite:///expenses.db` | SQLite or PostgreSQL URL |\n| `CURRENCY` | `₹` | Currency symbol |\n| `DEFAULT_USER` | `default` | User ID for multi-user setups |\n\nPostgreSQL example:\n```\nDATABASE_URL=postgresql://user:pass@localhost:5432/expenses\n```\n\n---\n\n## Tools\n\n| Tool | Description | Read-only |\n|---|---|---|\n| `expense_add` | Save expense or income | ❌ |\n| `expense_search` | Filter by text, date, category, amount | ✅ |\n| `expense_summary` | today / week / month / year totals | ✅ |\n| `expense_delete` | Delete with Pydantic confirmation prompt | ❌ |\n| `expense_insights` | Spending patterns and top categories | ✅ |\n| `budget_set` | Set monthly category budget | ❌ |\n| `budget_list` | View budgets with usage % | ✅ |\n| `goal_create` | Create savings goal | ❌ |\n| `goal_update` | Add money toward goal | ❌ |\n| `goal_list` | View goals with progress bars | ✅ |\n\n## Resources\n\n| URI | Description |\n|---|---|\n| `expense://summary/month` | Current month summary |\n| `expense://budgets/current` | This month's budgets |\n| `expense://goals/all` | All savings goals |\n\n## Prompts\n\n| Prompt | Title | Description |\n|---|---|---|\n| `monthly_review` | Monthly Review | Start a full month spending review |\n| `budget_setup` | Budget Setup | Auto-suggest budgets from history |\n| `savings_plan` | Savings Plan | Create a plan for a savings goal |\n\n---\n\n## Usage Examples\n\nJust talk naturally in any MCP client:\n\n```\n\"spent 500 on groceries\"\n\"show food expenses this week\"\n\"how much did I spend last month?\"\n\"set food budget to 5000\"\n\"am I within budget?\"\n\"save 1000 toward my iPhone goal\"\n\"give me spending insights\"\n\"delete expense #12\"\n```\n\n---\n\n## Architecture\n\n- **MCP SDK** v1.26.0 with `FastMCP` + `json_response=True`\n- **Typed lifespan** — DB engine managed via `AppContext` dataclass\n- **SQLAlchemy 2.0** — `DeclarativeBase`, `sessionmaker`\n- **Pydantic v2** — input validation, elicitation schemas\n- **Tool annotations** — `readOnlyHint`, `destructiveHint`, `idempotentHint`\n- **Context logging** — `ctx.info()`, `ctx.warning()` in tools\n\n### Database Schema\n\n```\nexpenses  — id, user_id, amount, category, description, type, date, source, created_at\nbudgets   — id, user_id, category, amount, month\ngoals     — id, user_id, name, target, saved, deadline\n```\n\n---\n\n## License\n\nMIT — free to use, modify, and distribute.\n",
  "bytes": 4458,
  "sha": "4b110bf82574892fab0bd7bd0438ee86ba3a060acfb268431ce97cc86a2c56ac",
  "repo_slug": "justfsl50/expense-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_justfsl50_expense_mcp_631b765e/readme"
}