使用说明

💸 ExpTrack——基于人工智能的支出跟踪器

和克劳德谈谈。跟踪你的开支。想象一下你的支出。

告诉克劳德你花了多少钱，剩下的就交给他了。

✨ 什么是ExpTrack？

ExpTrack是一个 会话式费用跟踪器 由Claude AI提供支持。您只需告诉Claude：

“花了₹450 今晚Zomato晚餐” “我这周花了多少钱？” “删除我昨天的优步费用” “我这个月超出预算了吗？”

Claude理解你，调用正确的工具，并将所有内容记录到你的Supabase数据库中。一个漂亮的网络仪表板可以让你直观地了解你的支出——每30秒自动刷新一次。

🏗️ 建筑

┌─────────────────────────────────────────────────────────┐
│                     You (User)                          │
│          Claude Desktop / Claude Code                   │
└────────────────────────┬────────────────────────────────┘
                         │ MCP Protocol
                         ▼
┌─────────────────────────────────────────────────────────┐
│              FastMCP Server (Python)                    │
│         Natural language → Tool calls                   │
│   add · list · edit · delete · summarize · budget       │
└────────────────────────┬────────────────────────────────┘
                         │ Read / Write
                         ▼
┌─────────────────────────────────────────────────────────┐
│              Supabase (PostgreSQL)                      │
│            expenses · budgets tables                    │
└────────────────────────┬────────────────────────────────┘
                         │ Read only
                         ▼
┌─────────────────────────────────────────────────────────┐
│              FastAPI (REST API)                         │
│     /api/stats · /api/expenses · /api/budgets           │
└────────────────────────┬────────────────────────────────┘
                         │ Fetch
                         ▼
┌─────────────────────────────────────────────────────────┐
│          Dashboard (HTML + CSS + JS)                    │
│   KPI cards · Charts · Table · Budget tracker           │
└─────────────────────────────────────────────────────────┘

📁 项目结构

expense-tracker/
│
├── 📂 expense_tracker_mcp_server/     # MCP Server (Claude talks to this)
│   ├── main.py                        # FastMCP entry point
│   ├── mcp_init.py                # Shared mcp instance
│   ├── database/
│   │   ├── client.py                  # Supabase client init
│   │   └── queries.py                 # All DB operations
│   ├── tools/
│   │   └── tools.py                   # All MCP tool definitions
│   ├── utils.py                       # IST timezone, helpers
│   ├── .env                           # 🔒 SUPABASE_URL + SUPABASE_KEY
│   ├── pyproject.toml
│   └── uv.lock
│
├── 📂 api/                            # FastAPI (Dashboard data layer)
│   ├── main.py                        # FastAPI app
│   ├── routers/
│   │   ├── expenses.py                # GET /api/expenses
│   │   ├── stats.py                   # GET /api/stats/*
│   │   └── budgets.py                 # GET /api/budgets/*
│   ├── database/
│   │   └── client.py                  # Supabase client (copy)
│   ├── .env                           # 🔒 SUPABASE_URL + SUPABASE_KEY
│   ├── pyproject.toml
│   └── uv.lock
│
├── 📂 dashboard/                      # Web Dashboard
│   ├── index.html                     # Entry point
│   ├── css/
│   │   ├── base.css                   # Tokens, reset, typography
│   │   ├── layout.css                 # Sidebar, grid, sections
│   │   ├── components.css             # Cards, badges, tables
│   │   └── charts.css                 # Chart containers, legends
│   ├── js/
│   │   ├── api.js                     # All API fetch calls
│   │   ├── kpi.js                     # KPI cards renderer
│   │   ├── charts.js                  # All Chart.js renderers
│   │   ├── table.js                   # Expense table + filters
│   │   └── app.js                     # Main init + auto-refresh
│   └── assets/
│
├── .gitignore
├── .python-version                    # 3.12 (shared across projects)
└── README.md

🚀 快速开始

先决条件

紫外线 --Python包管理器
克劳德桌面版或克劳德代码
Supabase 帐户（免费版有效）

1.️⃣ 克隆仓库

git clone https://github.com/k-Rohit/mcp_servers.git
cd expense-tracker

2.️⃣ 设置Supabase

首选网站 supabase.com → 创建一个新项目
首选 SQL编辑器 并运行：

CREATE TABLE expenses (
  id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  amount         NUMERIC(10,2) NOT NULL,
  currency       TEXT DEFAULT 'INR',
  description    TEXT NOT NULL,
  category       TEXT,
  date           DATE NOT NULL DEFAULT CURRENT_DATE,
  tags           TEXT[],
  notes          TEXT,
  created_at     TIMESTAMPTZ DEFAULT NOW(),
  updated_at     TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE budgets (
  id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  month      TEXT NOT NULL,
  amount     NUMERIC(10,2) NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

首选 设置→ API 并复制：
- 项目Url → SUPABASE_URL
- service_role密钥 → SUPABASE_KEY

3.️⃣ 设置MCP服务器

cd expense_tracker_mcp_server

# create .env
echo "SUPABASE_URL=https://xxxxx.supabase.co" > .env
echo "SUPABASE_KEY=your-service-role-key" >> .env

# install dependencies
uv sync

4.️⃣ 连接到克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （Mac）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "expense-tracker": {
      "command": "/absolute/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/expense-tracker/expense_tracker_mcp_server",
        "main.py"
      ]
    }
  }
}

找到绝对路径 uv:

对于Windows： where uv
对于macOS： which uv

重新启动克劳德桌面。你应该看看🔨 聊天输入中的锤子图标。

5.️⃣ 设置FastAPI

cd ../api

# create .env (same credentials)
echo "SUPABASE_URL=https://xxxxx.supabase.co" > .env
echo "SUPABASE_KEY=your-service-role-key" >> .env

# install and run
uv sync
uv run uvicorn main:app --reload --port 8000

API文件可在 http://localhost:8000/docs

6.️⃣ 打开仪表板

cd ../dashboard
python3 -m http.server 3000

打开 http://localhost:3000 在您的浏览器中。

注：在打开仪表板之前，请确保FastAPI正在端口8000上运行。

🤖 MCP工具参考

以下是Claude在与它聊天时可以使用的工具：

工具	描述	示例提示
`add_expense`	记录新的支出	“花了500美元吃Swiggy晚餐”
`get_expenses_by_date`	在某个日期列出费用	“显示我昨天的开支”
`list_expenses`	按期间+类别列出	“显示本周的食品费用”
`edit_expense`	编辑现有费用	“将Zomato金额更改为350”
`delete_expense_tool`	删除费用	“从今天起删除我的优步”
`summarize_expenses`	支出汇总+明细	“总结本月支出”
`summarize_by_month`	特定月份的总计	“我一月份花了多少钱？”
`set_budget`	设定月度预算	“将我3月份的预算定为15000”
`check_budget`	预算与实际	“我这个月超出预算了吗？”
`list_all`	所有费用	“让我看看我的所有开支”

💬 对话示例

You:    "spent 450 on zomato dinner"
Claude: ✅ Expense added!
          Amount   : ₹450
          Desc     : Zomato dinner
          Category : Food
          Date     : 2026-02-28

You:    "how much did I spend this week?"
Claude: 📊 This Week (2026-02-24 → 2026-02-28)
          Total: ₹3,240

          Food       ₹1,800   55.6%  ████████████
          Travel     ₹980     30.2%  ██████
          Shopping   ₹460     14.2%  ███

You:    "delete my uber from today"
Claude: Here are today's expenses:
          1. [df55f75c] ₹320  | Swiggy Lunch   | Food
          2. [a1b2c3d4] ₹180  | Uber to Office | Travel
        Which one to delete?

You:    "the uber one"
Claude: Are you sure you want to delete:
        Uber to Office — ₹180 — 2026-02-28?

You:    "yes"
Claude: 🗑️ Deleted: Uber to Office ₹180

You:    "set my budget for March to 20000"
Claude: ✅ Budget set: ₹20,000 for 2026-03

You:    "am I over budget this month?"
Claude: 💰 Budget vs Actual — 2026-02
          Budget    : ₹18,000
          Spent     : ₹15,240
          Remaining : ₹2,760
          Used      : 84.7%
          Status    : 🟢 WITHIN BUDGET

📊 仪表板功能

web仪表板每30秒自动刷新一次，并显示：

小部件	描述
KPI卡	今天·本周·本月·平均/天·与上月相比
每日柱状图	过去30天的支出
类别甜甜圈	按类别细分，并附有图例
月度趋势	6个月支出趋势线
支付方式	UPI·卡·现金·网上银行甜甜圈
星期几	每日平均花费——斑点模式
类别趋势	堆叠式酒吧——6个月以上的类别
前5项支出	本月单笔支出最高
预算与实际	进度条显示超过/低于状态
费用表	所有带有搜索+过滤器的交易

🌐 API终点

方法	端点	描述
`GET`	`/api/expenses/`	所有带有可选过滤器的费用
`GET`	`/api/expenses/by-date?date=YYYY-MM-DD`	特定日期的费用
`GET`	`/api/stats/kpi`	KPI卡数据
`GET`	`/api/stats/daily?days=30`	过去N天的每日消费
`GET`	`/api/stats/category?month=YYYY-MM`	类别细分
`GET`	`/api/stats/monthly?months=6`	每月总计
`GET`	`/api/stats/category-trend?months=6`	按月份分类
`GET`	`/api/stats/payment-method`	付款方式明细
`GET`	`/api/stats/top-expenses?limit=5`	本月前N项支出
`GET`	`/api/stats/weekday-pattern`	每周平均花费
`GET`	`/api/budgets/`	所有预算
`GET`	`/api/budgets/vs-actual?month=02&year=2026`	预算与实际

⚙️ 环境变量

两者 expense_tracker_mcp_server/.env 和 api/.env 需要：

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-service-role-secret-key

⚠️ 始终使用 service_role 密钥（不是匿名密钥）。永不承诺 .env 到git。

🛠️ 技术栈

层	技术
AI协议	FastMCP 3.0+
MCP客户端	克劳德桌面/克劳德代码
后端API	快速API +乌维科恩
数据库	Supabase （PostgreSQL）
包管理器	紫外线
Python版本	3.12
仪表板	HTML+CSS+JS+ Chart.js
字体	服装+JetBrains单色

🗺️ 路线图

[x] 配备所有CRUD工具的MCP服务器
[x] Supabase集成
[x] FastAPI REST层
[x] 带图表的Web仪表板
[x] 每30秒自动刷新一次
[x] 预算跟踪
[ ] 🔜 Telegram机器人集成
[]收据图像上传（通过Claude Vision进行OCR）
[]CSV/Excel导出
[]经常性费用检测
[]移动响应式仪表板
[]多币种支持

🤝 贡献

分叉回购
创建您的分支： git checkout -b feature/your-feature
提交您的更改： git commit -m "feat: add your feature"
推到分支： git push origin feature/your-feature
打开拉取请求

建于❤️ 使用Claude AI·FastMCP·Supabase

如果这对你有帮助，给它一个⭐