expense-mcp

💰 expense-mcp

MCP 服务形式的个人开支追踪器——兼容 Claude Desktop、Cursor、nanobot、Windsurf 和任何兼容 MCP 的客户端。

---

功能

• 📝 追踪开支和收入，并为其添加类别和描述
• 📊 开支汇总——今日、本周、本月、本年
• 💳 预算管理——按类别设置限额，在达到 80%/100% 时收到提醒
• 🎯 储蓄目标——创建目标，并通过可视化进度条追踪进度
• 📈 开支洞察——主要类别、日均开支、开支最多的日期
• 🗑️ 安全删除——通过基于 Pydantic 的征询请求确认
• 🔄 双传输模式——stdio（本地）+ streamable HTTP（远程）

---

安装

# 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 .

---

快速开始

Claude Desktop

添加到 %APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/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

配置相同——粘贴到相应应用的 MCP 设置中。

nanobot

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

HTTP 模式（远程 / 多客户端）

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

---

环境变量

变量	默认值	说明
DATABASE_URL	sqlite:///expenses.db	SQLite 或 PostgreSQL URL
CURRENCY	₹	货币符号
DEFAULT_USER	default	多用户设置中的用户 ID

PostgreSQL 示例：

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

---

工具

工具	说明	只读
expense_add	保存开支或收入	❌
expense_search	按文本、日期、类别、金额筛选	✅
expense_summary	今日 / 本周 / 本月 / 本年总额	✅
expense_delete	通过 Pydantic 确认提示删除	❌
expense_insights	开支模式和主要类别	✅
budget_set	设置每月类别预算	❌
budget_list	查看预算及使用率 %	✅
goal_create	创建储蓄目标	❌
goal_update	为目标增加资金	❌
goal_list	查看目标及进度条	✅

资源

URI	说明
expense://summary/month	本月汇总
expense://budgets/current	本月预算
expense://goals/all	所有储蓄目标

提示词

提示词	标题	说明
monthly_review	月度回顾	开始全面的月度开支回顾
budget_setup	预算设置	根据历史记录自动推荐预算
savings_plan	储蓄计划	为储蓄目标制定计划

---

使用示例

在任何 MCP 客户端中自然地进行对话：

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

---

架构

• MCP SDK v1.26.0，使用 FastMCP + json_response=True
• 类型化生命周期——通过 AppContext 数据类管理数据库引擎
• SQLAlchemy 2.0——DeclarativeBase、sessionmaker
• Pydantic v2——输入验证、征询请求模式
• 工具注解——readOnlyHint、destructiveHint、idempotentHint
• 上下文日志记录——在工具中使用 ctx.info()、ctx.warning()

数据库架构

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

---

许可证

MIT——可免费使用、修改和分发。