内容
# 费用跟踪 MCP 服务器
个人费用跟踪与管理的模型上下文协议（MCP）服务器。通过与 AI 助手的自然语言对话，跟踪您的日常费用，管理收入/工资，并深入了解您的消费模式。
## 功能
- 💰 **费用管理**：添加、编辑、删除和列出带有类别和子类别的费用
- 💵 **收入跟踪**：记录工资和其他收入来源
- 📊 **智能摘要**：按类别和日期范围获取消费明细
- 🏷️ **内置分类**：具有子类别的预定义类别，用于详细跟踪
- 📝 **自定义备注**：为任何交易添加备注以获取更好的上下文
- 💾 **本地存储**：所有数据存储在 SQLite 数据库中
- 📈 **工资摘要**：保存自定义财务摘要以供参考
---
## 安装
### 先决条件
- Python >= 3.13
- [uv](https://github.com/astral-sh/uv) （推荐的包管理器）
如果您没有 `uv`，请使用以下命令安装：
```bash
pip install uv
```
### 设置
克隆仓库：
```bash
git clone https://github.com/genaiwithms/expense-tracker-mcp.git
cd expense-tracker-mcp
```
安装依赖项：
```bash
uv add fastmcp
```
运行服务器：
```bash
python main.py
```
---
## 使用内置类别
我们提供内置类别以防止错误信息和重复（例如，Claude 可能将“Food”和“Dining”写为单独的类别）。使用我们的内置类别可确保您的费用跟踪的一致性和准确性。
**如何与 Claude 一起使用内置类别：**
1. 点击 ➕ 加号图标，附件文件处。
2. 选择“从费用跟踪器添加”。
3. 点击 `categories.json` 文件。
4. 现在您可以简单地问 Claude：
**“使用我附加的类别”**
这将帮助 Claude（或任何 MCP 客户端）为您使用正确的、一致的类别。
---
## 配置
### Claude 桌面版
将服务器添加到您的 Claude 桌面版配置文件中：
- **MacOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
示例配置：
```json
"ExpenseTracker": {
"command": "absolute \\path\\to\\uv",
"args": [
"run",
"--with",
"fastmcp",
"fastmcp",
"run",
"\\absolute\\path to \\Expense-tracker-mcp\\main.py"
],
"env": {},
"transport": "stdio",
"type": null,
"cwd": null,
"timeout": null,
"description": null,
"icon": null,
"authentication": null
}
```
**新用户的重要信息：**
将 `"absolute \\path\\to\\uv"` 替换为您的 `uv` 二进制文件的完整路径。
将 `"\\absolute\\path to \\Expense-tracker-mcp\\main.py"` 替换为此项目中您的 `main.py` 文件的完整路径。
如果您不确定 `uv` 的路径，请运行：
Mac/Linux
```bash
which uv
```
Windows
```powershell
where uv
```
---
## 使用示例
### 添加费用
- "添加昨天前往 Sargodha 的 50 卢比费用"
- "今天我花了 500 卢比吃东西，花了 300 卢比看病"
### 跟踪收入
- "我今天收到了 40,000 卢比的工资"
- "添加来自自由职业工作的 5000 卢比信用额度"
### 获取摘要
- "显示我这个月的全部费用"
- "我上周的总食品费用是多少？"
- "按类别总结我的消费"
- "我还剩多少工资？"
### 管理记录
- "编辑费用 #5，将金额更改为 600"
- "删除费用 #12"
- "显示 10 月 1 日至 10 月 10 日的所有费用"
---
## 可用工具
### 费用
- `add_expense` - 添加新的费用记录
- `delete_expense` - 按 ID 删除费用
- `edit_expense` - 编辑现有费用
- `list_expenses` - 列出某个日期范围内的费用
- `summarize` - 按类别获取费用摘要
### 收入/信用额度
- `add_credit` - 添加收入/工资记录
- `list_credits` - 列出某个日期范围内的信用额度
- `summarize_credits` - 按类别获取收入摘要
### 类别
- `list_categories` - 查看所有可用的类别和子类别
---
## 数据库架构
服务器使用 SQLite，包含以下表格：
- **expenses:** id, date, amount, category, subcategory, note
- **credits:** id, date, amount, category, note
---
## 开发
### 项目结构
```
expense-tracker-mcp/
├── main.py # MCP 服务器实现
├── categories.json # 类别定义
├── expenses.db # SQLite 数据库（自动创建）
├── pyproject.toml # 项目配置
└── README.md # 此文件
```
### 添加自定义类别
编辑 `categories.json` 以添加或修改费用类别和子类别。
---
## 隐私与安全
- 所有数据均存储在您的本地机器上
- 没有数据发送到外部服务器
- 数据库文件在项目目录中创建
- 适合个人财务跟踪
---
## 贡献
欢迎贡献！请随时提交拉取请求。
---
## 许可证
该项目是开源的，基于 MIT 许可证。
---
## 致谢
使用 FastMCP 构建 - 一个用于构建 MCP 服务器的 Python 框架。
---
## 支持
如有问题、疑问或建议，请在 GitHub 上提出问题。
> **注意：** 此 MCP 服务器设计用于个人使用。请始终备份您的 `expenses.db` 文件，以防止数据丢失。
