MCP Finance Tracker 💰
一个基于 Model Context Protocol (MCP) 的记账与分析服务，帮助你在自动化工作流中轻松完成账单记录与分类管理。无论是嵌入到智能助手，还是独立运行在服务器上，它都能提供清晰的数据结构与稳定的 API 支撑。
✨ 项目特色
- 🤝 原生 MCP 支持：采用 FastMCP 框架，实现高性能、低延迟的 MCP 服务端。
- 🗃️ 结构化账单管理：使用 MySQL 存储账单与分类数据，开箱即用的默认分类可快速开始记账。
- 📦 一键部署：提供 Docker 镜像与 docker-compose 编排，自动初始化数据库与字体资源。
- 🧩 工具即服务：内置
get_categories与record_billMCP Tool，可直接被任何兼容客户端调用。 - 📈 中文环境友好：预置
fonts-noto-cjk，确保图表与报表在中文环境下无乱码。
🧱 技术栈总览
| 模块 | 技术 | 说明 |
|---|---|---|
| 服务框架 | FastMCP | 实现 MCP 服务端与工具暴露 |
| 数据访问 | SQLAlchemy、PyMySQL | ORM 管理模型，连接 MySQL |
| 配置校验 | Pydantic | 保障配置、请求参数的合法性 |
| 部署 | Docker、docker-compose | 容器化部署与多服务编排 |
🚀 构建与部署指南
✅ 推荐：Docker Compose
- 克隆仓库
git clone https://github.com/yourusername/mcp-finance-tracker.git
cd mcp-finance-tracker- 启动服务
docker-compose up -d- 实时查看日志
docker-compose logs -f mcp_server首次启动会自动：
- 创建 MySQL 数据库与所需表结构。
- 写入默认分类（餐饮、交通、购物、收入）。
- 安装中文字体以支持图表渲染。
🛠️ 本地运行 / 二次开发
- 准备环境：确保已安装 Python 3.11+ 与 MySQL。
- 安装依赖
pip install -r requirements.txt- 配置环境变量
cp .env.example .env
# 编辑 .env 设置 DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME- 启动 MySQL（可选）
docker-compose up -d mysql- 运行服务
python -m mcp.mcp_server💡 如果需要在本地自定义图表字体，可将MCP_CHART_FONT_PATH指向对应的.ttf或.otf文件。
🔌 MCP 工具能力
| Tool 名称 | 用途 | 示例 |
|---|---|---|
get_categories | 查询所有记账分类及描述 | await get_categories() |
record_bill | 记录收入/支出账单 | await record_bill(amount=100.5, type="expense", category_id=1) |
record_bill 支持：
amount：正数金额。type：income或expense。category_id：可选分类 ID，缺省时记录为未分类。description：账单备注。
🗂 数据模型速览
分类（categories）
id：主键name：唯一分类名description：分类描述
账单（bills）
id：主键amount：金额type：income/expensecategory_id：外键关联分类description：备注信息
📁 项目结构
mcp-finance-tracker/
├── mcp/
│ ├── __init__.py # MCP 包初始化
│ ├── mcp_server.py # MCP 服务端主程序
│ ├── crud.py # 数据库 CRUD 操作
│ ├── config.py # 配置与环境变量
│ ├── schemas.py # Pydantic 数据模型
│ ├── models.py # SQLAlchemy 数据模型
│ └── database.py # 数据库会话管理
├── requirements.txt # Python 依赖列表
├── Dockerfile # Docker 镜像定义
├── docker-compose.yml # docker-compose 配置
├── .env.example # 环境变量示例
└── README.md # 项目说明📜 许可证
MIT License