使用说明

💸 ExpenseTracker——MCP服务器+全栈Web应用程序

一个适用于生产的个人理财系统 两种方式同时:

模式	它是什么	URL
MCP服务器	适用于Claude、ChatMCP和任何MCP客户端的AI原生工具	`https://academic-gold-weasel.fastmcp.app/mcp`
网络应用	带有身份验证、表单和报告的全栈仪表板	`https://academic-gold-weasel.fastmcp.app`

这两种模式共享相同的SQLite数据库、类别分类、预算规则和经常性费用引擎，因此您通过web UI输入的任何内容都可以立即被AI工具看到，反之亦然。

实时链接

资源	URL
🌐 Web应用程序	https://academic-gold-weasel.fastmcp.app
🤖 MCP端点	https://academic-gold-weasel.fastmcp.app/mcp
❤️ 健康检查	https://academic-gold-weasel.fastmcp.app/api/health
📂 类别API	https://academic-gold-weasel.fastmcp.app/api/categories

功能概述

MCP侧（AI/Claude）

✅ 21种工具，涵盖整个费用生命周期
✅ 6个实时资源（类别、今天的支出、本月、预算、经常性、历史统计数据）
✅ 无状态HTTP传输——适用于任何兼容MCP的客户端
✅ 异步SQLite后端(aiosqlite)使用WAL模式

Web应用端

✅ Google OAuth登录
✅ 电话OTP登录（Twilio验证）
✅ 每用户数据隔离
✅ 月度仪表板，包括总计、类别细分、趋势
✅ 费用、预算和经常性项目的完整CRUD
✅ 带有系统偏好检测的暗/亮主题
✅ “复制MCP URL”按钮——直接从UI获取服务器端点
✅ 响应式设计（移动+桌面）

MCP服务器——完整参考

如何连接

MCP端点：

https://academic-gold-weasel.fastmcp.app/mcp

运输： 无状态HTTP(POST /mcp)

克劳德桌面(`claude_desktop_config.json`)

{
  "mcpServers": {
    "ExpenseTracker": {
      "url": "https://academic-gold-weasel.fastmcp.app/mcp"
    }
  }
}

ChatMCP/检查员

将端点URL直接粘贴到服务器字段中：

https://academic-gold-weasel.fastmcp.app/mcp

光标/风帆/VS代码（MCP扩展名）

{
  "mcp": {
    "servers": {
      "ExpenseTracker": {
        "url": "https://academic-gold-weasel.fastmcp.app/mcp",
        "transport": "http"
      }
    }
  }
}

所有工具

🧾 原油费用

工具	参数	说明
`add_expense`	`date`, `amount`, `category`, `subcategory?`, `note?`, `tags?`, `payment_mode?`, `currency?`	添加单个费用条目
`update_expense`	`expense_id`，要更改的任何字段	编辑现有费用的一个或多个字段
`delete_expense`	`expense_id`	永久删除费用
`bulk_add_expenses`	`expenses` （对象列表）	在一次通话中插入许多费用
`get_expense`	`expense_id`	按ID获取单个支出

add_expense --完整参数参考：

参数	类型	必填	备注
`date`	string	✅	格式： `YYYY-MM-DD`
`amount`	浮动	✅	正数
`category`	string	✅	必须与类别名称匹配（请参见分类)
`subcategory`	string	--	可选子类别
`note`	string	--	自由文本描述
`tags`	string	--	逗号分隔，例如。 `"work,reimbursable"`
`payment_mode`	string	--	`cash` / `upi` / `card` / `netbanking` / `emi` / `other`
`currency`	string	--	3个字母的代码，默认值 `INR`

🔍 查询和列表

工具	参数	说明
`list_expenses`	`start_date`, `end_date`, `category?`, `payment_mode?`, `min_amount?`, `max_amount?`, `tags?`, `limit?`	使用丰富的过滤器列出费用
`search_expenses`	`keyword`, `start_date?`, `end_date?`, `limit?`	在笔记、子类别、标签、类别中进行全文搜索
`top_expenses`	`start_date`, `end_date`, `n?`, `category?`	返回一个范围内N个最大的支出

📊 报告和分析

工具	参数	返回
`summarize`	`start_date`, `end_date`, `category?`, `group_by_subcategory?`	包含交易计数的类别（或子类别）总计
`monthly_report`	`year`, `month`	总计、类别细分、每日总计、前5项支出、预算状态
`yearly_report`	`year`	年度总计、逐月细分、类别细分
`compare_months`	`month1`, `month2` （YYYY-MM）	并列总计和每个类别的变化，差异百分比
`spending_trends`	`months?` （默认值6）， `category?`	过去N个月的环比趋势
`daily_breakdown`	`start_date`, `end_date`, `category?`	每日支出总额
`expense_stats`	`start_date`, `end_date`	总计、计数、平均值、中位数、最小值、最大值、标准偏差、平均值/天
`payment_mode_summary`	`start_date`, `end_date`	按付款方式分组的支出
`export_csv`	`start_date`, `end_date`, `category?`	返回准备保存或显示的CSV字符串

💰 预算管理

工具	参数	说明
`set_budget`	`month` （YYYY-MM）， `category`, `amount`	设置或更新某个类别的每月支出上限
`get_budgets`	`month`	一个月的所有预算，包括实际预算和已使用百分比
`delete_budget`	`month`, `category`	删除预算条目

🔁 经常性支出

工具	参数	说明
`add_recurring`	`description`, `amount`, `category`, `subcategory?`, `payment_mode?`, `frequency`, `next_due?`	注册定期模板（租金、EMI、订阅）
`list_recurring`	`active_only?`	列出所有活动的重复模板
`log_recurring`	`recurring_id`, `date_override?`	从模板中发布实际费用并预付 `next_due`
`delete_recurring`	`recurring_id`	软删除（停用）定期模板

frequency 值： monthly · weekly · yearly

所有资源

资源是以JSON形式公开的只读快照。任何MCP客户端都可以直接读取它们。

URI	描述
`expense:///categories`	完整类别+子类别分类 `categories.json`
`expense:///summary/today`	今天的总数和每个类别的细分
`expense:///summary/this_month`	当月总计、每个类别的预算进度、已用天数
`expense:///recurring/due_soon`	所有重复项目 `next_due` 在接下来的7天内
`expense:///budgets/status`	本月预算与每个配置类别的实际预算
`expense:///stats/all_time`	所有时间交易计数、总计、平均值、前5类

示例提示

将这些直接粘贴到Claude或任何与MCP连接的AI中：

Add an expense: ₹450 for lunch today, category food, subcategory dining_out, paid by UPI.

Show all my expenses from April 1 to April 5, 2026.

Give me a full monthly report for March 2026.

Compare my spending in February and March 2026.

Set a budget of ₹8000 for food in April 2026.

Show my budget status for this month.

What are my top 10 largest expenses this year?

Add a recurring expense: Netflix ₹649/month, category subscriptions/streaming, next due 2026-05-01.

Log this month's Netflix payment.

Show spending trends for the last 6 months.

Export my April 2026 expenses as CSV.

Search for all expenses with the note "office".

Show stats for Q1 2026 (Jan 1 to Mar 31).

Web应用程序——完整参考

实时网址： https://academic-gold-weasel.fastmcp.app

认证

web应用程序支持两种登录方法：

谷歌登录

使用您的Google帐户单击OAuth
无需密码
自动提取个人资料图片、姓名和电子邮件

电话OTP

输入您的电话号码和国家代码（例如。 +91XXXXXXXXXX)
通过短信接收一次性代码（由Twilio Verify提供支持）
输入登录代码

会话将持续 30天。浏览器重新启动后，您仍保持登录状态。

仪表盘

登录后，仪表板是主屏幕。它显示：

第节	显示内容
月度总计	本日历月迄今为止的总支出
类别细分	带有预算进度条的每个类别总计（如果已设置预算）
近期开支	最近几笔交易概览
定期到期	7天内即将进行的定期付款
MCP连接面板	带有一键复制按钮的实时MCP端点URL

费用管理（网络）

可在开支选项卡：

增加支出 --日期、金额、类别（下拉菜单）、子类别、备注、标签、支付方式、货币
查看费用 --可按日期范围筛选的分页列表
编辑费用 --单击任何条目以更新任何字段
删除费用 --确认后删除
所有更改都会立即同步到共享数据库（在AI工具中也可见）

预算（网络）

可在预算选项卡：

设定预算 --选择一个月，选择一个类别，设置一个金额
预算跟踪器 --显示支出与限额的可视化进度条
超预算警报 --当类别超过其上限时，突出显示行
删除预算 --删除任何预算条目

经常性费用（网络）

可在 循环的 选项卡：

添加定期 --描述、金额、类别、频率（每月/每周/每年）、下一个到期日
查看活动重复 --按下一个截止日期排序
记录付款 --将一次事件标记为已支付，并自动提前下一个到期日
停用 --软删除而不丢失历史记录

配置文件和设置

可在简介选项卡：

字段	描述
全名	仪表板上显示的显示名称
城市	可选位置
月收入	用于计算储蓄百分比
储蓄目标	每月目标储蓄金额
默认货币	UI上显示的货币

数据模型

费用字段

字段	类型	注释
`id`	integer	自动递增的主键
`date`	文本	`YYYY-MM-DD`
`amount`	实数	正数
`category`	text	主要类别
`subcategory`	text	可选子类别
`note`	text	自由形式描述
`tags`	text	逗号分隔的标签
`payment_mode`	文本	`cash`, `upi`, `card`, `netbanking`, `emi`, `other`
`currency`	text	默认值 `INR`
`created_at`	text	插入时设置的UTC时间戳

其他桌子

表	目的
`budgets`	每个类别的月度上限(`month`, `category`, `amount`)
`recurring`	具有频率和重复性的模板 `next_due`
`app_users`	Web应用程序用户配置文件（Google+手机身份验证）
`app_sessions`	过期会话令牌
`app_otp_codes`	带TTL的一次性密码
`app_expenses`	每用户费用记录（网络应用程序）
`app_budgets`	每用户预算（网络应用程序）
`app_recurring`	每个用户的重复模板（web应用程序）

分类

20个顶级类别，每个类别都定义了子类别 categories.json:

类别	子类别示例
`food`	杂货、水果蔬菜、外出就餐、咖啡茶、外卖
`transport`	燃料、公共交通、出租车、停车场、车辆服务
`housing`	租金、维修费、物业税、维修服务、家具
`utilities`	电、水、互联网、宽带、手机、电视
`health`	药物、医生咨询、诊断实验室、健康知识
`education`	书籍、课程、在线订阅、考试费、研讨会
`family_kids`	学费、日托、玩具、游戏、衣服、活动、生日
`entertainment`	电影_活动，流媒体_订阅，游戏_应用程序，郊游
`shopping`	服装、鞋类、电子产品、小工具、电器、家居装饰
`subscriptions`	saas_tools、cloud_ai、音乐视频、存储备份
`personal_care`	盐_水疗、美容、化妆品、卫生
`gifts_donations`	礼物_个人，慈善_捐赠，节日
`finance_fees`	银行收费、滞纳金、利息、经纪费
`business`	软件工具、托管域名、营销广告、承包商付款
`travel`	航班、酒店、火车巴士、签证护照、当地交通
`home`	家居用品、清洁用品、厨具、香蒜酱控制
`pet`	食物、兽医、美容、用品
`taxes`	所得税、消费税、专业税、薪酬
`investments`	共同基金、股票、fd_rd、黄金、加密货币
`misc`	未分类、四舍五入、其他

本地开发

先决条件

Python 3.13+
uv 包管理器

设置

# Clone the repo
git clone https://github.com/Sanjoy-Chattopadhay/Expense-Tracker-Expense-Manager.git
cd Expense-Tracker-Expense-Manager

# Install dependencies
uv sync

# Copy env template and fill in values
cp .env.example .env

跑

# Start the server (web app + MCP endpoint)
uv run python main.py

端点	URL
Web应用程序	http://localhost:8000
MCP端点	http://localhost:8000/mcp
健康检查	http://localhost:8000/api/health

直接与Uvicorn一起跑步

uv run uvicorn app:app --host 0.0.0.0 --port 8000 --reload

将本地MCP连接到Claude Desktop

{
  "mcpServers": {
    "ExpenseTracker-local": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

环境变量

复制 .env.example 到 .env 并配置：

cp .env.example .env

变量	必填	默认	描述
`PORT`	—	`8000`	服务器端口
`DB_PATH`	--	自动检测	显式SQLite文件路径。自动解析为 `./data/expenses.db` 然后 `/tmp/expenses.db`
`SECURE_COOKIES`	—	`true`	设置 `false` 仅用于本地HTTP开发
`SESSION_TTL_DAYS`	—	`30`	网络会话持续多长时间
`OTP_TTL_MINUTES`	—	`10`	手机OTP码的有效期有多长
`GOOGLE_CLIENT_ID`	✅ 用于Google身份验证	--	来自Google Cloud控制台的OAuth Web客户端ID
`MCP_URL`	✅ 用于UI复制按钮	--	您的公共MCP端点URL
`TWILIO_ACCOUNT_SID`	--	--	Twilio帐户SID（如果未设置，OTP将回退到演示模式）
`TWILIO_AUTH_TOKEN`	--	--	Twilio授权令牌
`TWILIO_VERIFY_SERVICE_SID`	--	--	Twilio验证服务SID

注：没有Twilio凭据，应用程序仍然可以工作——OTP代码被记录到服务器控制台，而不是通过短信发送，这对开发很有用。

部署

FastMCP地平线（当前）

此服务器部署在 FastMCP地平线.推到 main 以触发重新部署。

MCP端点： https://academic-gold-weasel.fastmcp.app/mcp

渲染（替代）

A. render.yaml 包含用于一键渲染部署的持久磁盘，安装在 /app/data:

在Render仪表板中连接您的GitHub仓库
渲染将检测 render.yaml 自动地
在Render仪表板中设置secret env变量：
- GOOGLE_CLIENT_ID
- MCP_URL
- TWILIO_ACCOUNT_SID
- TWILIO_AUTH_TOKEN
- TWILIO_VERIFY_SERVICE_SID
部署

码头工人

# Build
docker build -t expense-tracker .

# Run
docker run -p 8000:8000 \
  -e GOOGLE_CLIENT_ID=your_id \
  -e MCP_URL=http://localhost:8000/mcp \
  -v $(pwd)/data:/app/data \
  expense-tracker

数据库持久性说明

该应用程序使用SQLite。对于托管部署：

持久磁盘/卷装载 在 /app/data → 数据在重启和重新部署后仍能存活✅
临时文件系统 （例如Vercel、AWS Lambda）→ 重新部署时擦除数据❌

Render、Railway、Fly.io和自托管Docker都支持卷挂载。

建筑

┌─────────────────────────────────────────────────────────┐
│                        main.py                          │
│                                                         │
│  FastMCP("ExpenseTracker")                              │
│  ├── 21 MCP Tools  (async, aiosqlite)                   │
│  ├── 6  MCP Resources (sync, sqlite3)                   │
│  └── register_web_routes(mcp, DB_PATH, ...)             │
│       └── webapp.py                                     │
│            ├── /api/auth/*    (Google + OTP)            │
│            ├── /api/expenses  (CRUD)                    │
│            ├── /api/budgets   (CRUD)                    │
│            ├── /api/recurring (CRUD + log)              │
│            ├── /api/dashboard                           │
│            ├── /api/public-config  → MCP_URL            │
│            └── /  → serves web/index.html              │
│                                                         │
│  SQLite DB (data/expenses.db)                           │
│  ├── expenses        budgets         recurring          │
│  ├── app_users       app_sessions    app_otp_codes      │
│  ├── app_expenses    app_budgets     app_recurring       │
│                                                         │
└─────────────────────────────────────────────────────────┘
         ▲                              ▲
   MCP Clients                    Web Browser
   (Claude, ChatMCP,           (web/index.html +
    Cursor, Inspector)          app.js + styles.css)

关键设计决策：

单个FastMCP实例通过以下方式为MCP协议和自定义HTTP路由提供服务 @mcp.custom_route
MCP工具使用 aiosqlite （异步）；MCP资源使用 sqlite3 （同步——FastMCP的资源模型要求）
web应用程序有自己的用户/会话表(app_*)用于多用户隔离；MCP工具在共享平台上运行 expenses 桌子
DB路径在启动时通过写探测回退链解析，因此服务器可以在任何平台上启动

技术栈

层	技术
MCP框架	FastMCP 3.2+
Web框架	Starlette（通过FastMCP自定义路由）
ASGI服务器	Uvicorn
数据库	SQLite通过 `aiosqlite` （异步）+ `sqlite3` （同步）
身份验证	谷歌OAuth 2.0(`google-auth`)+Twilio验证OTP
前端	普通HTML+CSS+JS（零框架依赖）
包管理器	`uv`
运行时	Python 3.13+
部署	FastMCP Horizon/Docker/Render

项目结构

.
├── main.py              # MCP server — all tools, resources, and app entry point
├── webapp.py            # Web app routes — auth, CRUD API, static file serving
├── app.py               # Minimal ASGI entry point for uvicorn
├── categories.json      # Expense category + subcategory taxonomy
├── web/
│   ├── index.html       # Single-page web application
│   ├── app.js           # Frontend logic (state, API calls, UI handlers)
│   └── styles.css       # Theme system, layout, responsive design
├── data/
│   └── expenses.db      # SQLite database (git-ignored)
├── Dockerfile           # Container image definition
├── render.yaml          # Render.com deployment config with persistent disk
├── pyproject.toml       # Python project metadata and dependencies
├── uv.lock              # Locked dependency tree
└── .env.example         # Template for all required environment variables

许可证

麻省理工学院——自由使用，感谢归因。