使用说明

💰 MCP服务器费用

轻量级的本地首创 模型上下文协议（MCP）服务器 用于跟踪个人和业务支出。它公开了任何兼容MCP的AI客户端（如Claude Desktop）都可以调用的工具，用于添加、列出和汇总费用——所有这些都存储在本地SQLite数据库中——可选 谷歌日历集成一 预算+警报 系统，以及a 信用（收入）体系 这会让你的预算与你的实际收入挂钩。

✨ 特性

📥 增加费用 带有日期、金额、类别、可选子类别和注释
📅 同步到谷歌日历 --在用户批准后将费用记录为日历事件
📋 列出费用 按日期范围筛选
📊 汇总费用 在任何日期范围内按类别
💳 信用体系 --记录你的收入（工资、自由职业者、租金、奖金等），这样系统就知道你每月的实际可支配收入
💰 预算+警报 --根据您的收入，为每个类别设定每月支出限额：
- ⚠️ 当您达到类别预算的80%时发出警告
- 🚨 超过类别预算时发出警报
- 💡 当消费速度比平时快时，会发出节奏警报
- 🚨 当总预算超过总收入时发出警报
- 🚨 当总支出超过总收入时发出警报
- ⚠️ 低储蓄率警告
📅 月度概览 --一次性财务快照：收入与预算、支出与储蓄
🗂️ 20个内置类别 包含详细的子类别
💾 本地SQLite存储 --你的数据永远不会离开你的机器
🔐 人在循环（HITL） --日历事件仅在用户明确确认后创建
⚡ 建于 FastMCP 实现干净、最小的设置

📋 需求

要求	版本
Python	≥3.13
紫外线	最新消息
fastmcp	<3.0.0

🚀 安装

1.克隆存储库

git clone https://github.com/your-username/expense-mcp-server.git
cd expense-mcp-server

2.安装依赖项

uv sync

没有 uv? 先安装：
pip install uv

🔑 谷歌日历设置（可选）

要启用 add_to_calendar 工具，您需要一个Google Cloud OAuth2凭据文件。

首选谷歌云控制台并创建/选择一个项目
启用 谷歌日历API
创建 OAuth 2.0凭据 （桌面应用程序类型）并下载为 credentials.json 在项目根中
首次运行时，将打开一个浏览器窗口进行授权；一 token.json 自动保存

⚠️ 保持 credentials.json 和 token.json 超出版本控制（已在 .gitignore).

🔧 使用Claude Desktop进行配置

将此添加到您的 claude_desktop_config.json:

窗户： %APPDATA%\Claude\claude_desktop_config.json
macOS/Linux： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ExpenseTracker": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\YourName\\Desktop\\Expense MCP Server",
        "run",
        "main.py"
      ]
    }
  }
}

保存后重新启动Claude Desktop。 ExpenseTracker 将显示为已连接的工具。

🛠️ 可用工具

支出工具

`add_expense`

添加新费用。自动检查活动预算和收入健康状况，如果超过任何阈值，则返回警报。

参数	类型	必填	说明
`date`	`string`	✅	在……约会 `YYYY-MM-DD` 格式
`amount`	`float`	✅	费用金额
`category`	`string`	✅	主要类别（例如。 `food`, `transport`)
`subcategory`	`string`	❌	可选子类别
`note`	`string`	❌	可选注释

`add_to_calendar`

为费用创建Google日历事件（仅在用户批准后）。

`list_expenses`

列出两个日期之间的所有费用。

`edit_expense`

纠正现有费用中的错误——错误的金额、错误的类别、错误的日期。仅更新您提供的字段。

参数	类型	必填	说明
`expense_id`	`int`	✅	要编辑的费用ID（从获取 `list_expenses`)
`date`	`string`	❌	更正日期 `YYYY-MM-DD`
`amount`	`float`	❌	更正金额
`category`	`string`	❌	更正类别
`subcategory`	`string`	❌	更正的子类别
`note`	`string`	❌	更新说明

编辑后，预算警报会自动重新评估。

示例提示：

“杂货金额应该是950而不是1200——固定费用为5。” “将费用类别3更改为运输。”

`delete_expense`

按ID删除费用条目。

`summarize`

按日期范围内的类别汇总支出。

💳 信贷（收入）工具

`add_credit`

当月收到的原木收入是预算系统的基础。一旦记录了收入，系统就可以验证你的预算没有超过你的收入，并跟踪实际的净储蓄。

参数	类型	必填	说明
`date`	`string`	✅	收到收入的日期， `YYYY-MM-DD`
`amount`	`float`	✅	收到金额
`source`	`string`	✅	标签： `salary`, `freelance`, `rental`, `bonus`, `interest`, `gift`, `refund`, `other`
`note`	`string`	❌	可选描述

示例提示：

“我今天拿到了7.5万英镑的工资。” “记录3月25日收到的15000份自由职业者付款。” “加上本月租金收入8000元。”

退货：

{
  "status": "ok",
  "id": 3,
  "date": "2026-03-01",
  "amount": 75000,
  "source": "salary",
  "month_summary": {
    "total_income": 75000,
    "total_budgeted": 42000,
    "total_spent": 18500,
    "unallocated": 33000,
    "net_savings": 56500
  }
}

`list_credits`

列出给定月份的所有收入条目。

参数	类型	必填	说明
`month`	`string`	❌	月份 `YYYY-MM` 格式。默认为当月

`edit_credit`

编辑现有的收入条目——更正错误的金额、更改来源或固定日期。只有您通过的字段才会更新；其他一切保持不变。

参数	类型	必填	说明
`credit_id`	`int`	✅	要编辑的条目的ID（从获取 `list_credits`)
`amount`	`float`	❌	更正金额
`source`	`string`	❌	更正了源标签
`date`	`string`	❌	更正日期 `YYYY-MM-DD`
`note`	`string`	❌	更新说明

编辑后，响应包括刷新 month_summary 如果你的预算现在超过了你更新的收入，就会发出警报。

示例提示：

“我的工资实际上是8万，而不是7.5万——修学分1。” “将学分来源2更改为自由职业者。”

`delete_credit`

按ID删除收入条目（使用 list_credits 查找ID）。

💰 预算工具

`set_budget`

为某个类别设置（或更新）每月支出上限。如果已记录收入，则响应包括 income_context 显示你的收入中有多少是分配的，有多少是未分配的。如果您的总预算超过收入，则会立即返回警报。

参数	类型	必填	说明
`category`	`string`	✅	类别到预算
`limit_amount`	`float`	✅	每月支出上限
`month`	`string`	❌	`YYYY-MM`.默认为当月

退货：

{
  "status": "ok",
  "message": "Budget set: food → 10,000 for 2026-03",
  "income_context": {
    "total_income": 75000,
    "total_budgeted": 42000,
    "unallocated": 33000
  }
}

`list_budgets`

列出一个月的所有预算，包括实际支出/剩余/已使用百分比和状态。

`check_budget_alerts`

返回一个月的所有活动警报——类别预算和收入健康状况。

`delete_budget`

删除类别+月份的预算。

📅 月度概览工具

`monthly_overview`

任何月份的完整一次性财务快照。将收入、预算和支出组合成一个结构化的响应。

参数	类型	必填	说明
`month`	`string`	❌	`YYYY-MM`.默认为当月

当用户问：

“这个月我过得怎么样？” “给我一份财务摘要。” “我的收入和支出是多少？”

退货：

{
  "month": "2026-03",
  "income": {
    "total": 83000,
    "by_source": [
      { "source": "freelance", "amount": 8000 },
      { "source": "salary", "amount": 75000 }
    ]
  },
  "budgets": {
    "total_allocated": 42000,
    "unallocated": 41000
  },
  "spending": {
    "total_spent": 18500,
    "net_savings": 64500,
    "savings_percent": 77.7
  },
  "category_breakdown": [
    { "category": "food", "budget": 10000, "spent": 8500, "remaining": 1500, "percent_used": 85.0, "status": "⚠️  WARNING" },
    { "category": "transport", "budget": 5000, "spent": 2100, "remaining": 2900, "percent_used": 42.0, "status": "✅ OK" }
  ],
  "alerts": ["✅ Finances look healthy this month."]
}

🚨 警报参考

警报	触发器
⚠️ 类别警告	支出≥类别预算的80%
🚨 超出类别	支出≥类别预算的100%
💡 节奏警报	支出率意味着月末超额（比比例节奏提前20%以上）
🚨 超额分配	总预算>总收入
🚨 支出>收入	当月总支出超过总收入
⚠️ 低储蓄	储蓄不到收入的10%

火警警报 自动进入 add_expense 相关情况下的回应。呼叫 check_budget_alerts 或 monthly_overview 随时获取完整状态快照。

📁 项目结构

expense-mcp-server/
├── main.py              # MCP server — all tools and resources
├── categories.json      # Supported categories and subcategories
├── credentials.json     # Google OAuth2 credentials (not committed)
├── token.json           # Google OAuth2 token (auto-generated, not committed)
├── expenses.db          # SQLite database (auto-created on first run)
├── pyproject.toml       # Project metadata and dependencies
├── uv.lock              # Locked dependency versions
└── README.md            # This file

🗄️ 数据库模式

-- Expense records
CREATE TABLE expenses (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    date        TEXT NOT NULL,        -- YYYY-MM-DD
    amount      REAL NOT NULL,
    category    TEXT NOT NULL,
    subcategory TEXT DEFAULT NULL,
    note        TEXT DEFAULT NULL
);

-- Monthly category budgets
CREATE TABLE budgets (
    id           INTEGER PRIMARY KEY AUTOINCREMENT,
    category     TEXT NOT NULL,
    month        TEXT NOT NULL,       -- YYYY-MM
    limit_amount REAL NOT NULL,
    UNIQUE(category, month)
);

-- Income / credit entries
CREATE TABLE credits (
    id     INTEGER PRIMARY KEY AUTOINCREMENT,
    date   TEXT NOT NULL,             -- YYYY-MM-DD
    amount REAL NOT NULL,
    source TEXT NOT NULL,             -- e.g. 'salary', 'freelance'
    note   TEXT DEFAULT NULL
);

所有表都是在第一次运行时自动创建的。

💡 推荐工作流程

1. Start of month:
   → add_credit "salary 75000"         # log your income first
   → set_budget food 10000             # allocate budgets (system checks vs income)
   → set_budget transport 5000
   → set_budget subscriptions 3000
   → ...

2. Throughout the month:
   → add_expense (alerts fire if nearing limits)
   → check_budget_alerts               # quick status check any time

3. End of month review:
   → monthly_overview                  # full income vs spending vs savings snapshot

🗂️ 分类

类别	子类别示例
`food`	杂货、外出就餐、咖啡、外卖
`transport`	燃料、公共交通、出租车、停车场
`housing`	租金、维修服务、家具
`utilities`	电力、互联网宽带、手机
`health`	药物、医生咨询、健康
`education`	书籍、课程、在线订阅、考试费用
`entertainment`	电影_活动、流媒体_订阅、郊游
`shopping`	服装、电子产品、家居装饰
`travel`	航班、酒店、火车巴士、签证护照
`investments`	共同基金、股票、加密货币、黄金
`business`	托管_域名、承包商_付款、营销_广告
`subscriptions`	saas_tools，云ai，音乐视频
`personal_care`	盐_水疗、美容、化妆品
`family_kids`	学费、日托、玩具、游戏
`gifts_donations`	礼物_个人，慈善_捐赠，节日
`finance_fees`	银行手续费、利息、经纪费
`taxes`	所得税、消费税、专业税
`home`	家居用品、清洁用品、厨具
`pet`	食物、兽医、美容、用品
`misc`	未分类，其他

💡 对话示例

"I got my salary of 75,000 today."
→ Logs credit, shows total income & unallocated amount

"Set my food budget to 10,000."
→ Sets budget, shows how much income is still unallocated

"Log 1,200 for groceries today."
→ Saves expense, fires ⚠️ warning if food budget is near limit

"Am I on track this month?"
→ check_budget_alerts: returns all warnings + income health

"Give me a full financial summary."
→ monthly_overview: income, budgets, spending, savings in one shot

🤝 贡献

欢迎拉取请求！思想：

经常性预算副本（自动将预算滚动到下个月）
多币种支持
导出到CSV/Excel
储蓄目标跟踪
通过环境变量配置时区

📄 许可证

开源。看许可证了解详情。

建于 FastMCP ·SQLite·谷歌日历·本地优先隐私

使用说明

💰 MCP服务器费用

✨ 特性

📋 需求

🚀 安装

1.克隆存储库

2.安装依赖项

🔑 谷歌日历设置（可选）

🔧 使用Claude Desktop进行配置

🛠️ 可用工具

支出工具

add_expense

add_to_calendar

list_expenses

edit_expense

delete_expense

summarize

💳 信贷（收入）工具

add_credit

list_credits

edit_credit

delete_credit

💰 预算工具

set_budget

list_budgets

check_budget_alerts

delete_budget

📅 月度概览工具

monthly_overview

🚨 警报参考

📁 项目结构

🗄️ 数据库模式

💡 推荐工作流程

🗂️ 分类

💡 对话示例

🤝 贡献

📄 许可证

相关 MCP

Google Ads管理MCP服务器

预算管理协议服务器

YNAB预算管理MCP服务

预算管理 MCP 服务

预算管理 MCP 服务器

发票管理服务器

`add_expense`

`add_to_calendar`

`list_expenses`

`edit_expense`

`delete_expense`

`summarize`

`add_credit`

`list_credits`

`edit_credit`

`delete_credit`

`set_budget`

`list_budgets`

`check_budget_alerts`

`delete_budget`

`monthly_overview`