AI导哈

财务追踪服务

一个基于Model Context Protocol (MCP)的记账与分析服务，帮助用户在自动化工作流中轻松完成账单记录与分类管理。

  • by nagisa77
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 nagisa77/mcp-finance-tracker

使用说明

MCP Finance Tracker 💰

一个基于 Model Context Protocol (MCP) 的记账与分析服务，帮助你在自动化工作流中轻松完成账单记录与分类管理。无论是嵌入到智能助手，还是独立运行在服务器上，它都能提供清晰的数据结构与稳定的 API 支撑。

✨ 项目特色

  • 🤝 原生 MCP 支持：采用 FastMCP 框架，实现高性能、低延迟的 MCP 服务端。
  • 🗃️ 结构化账单管理：使用 MySQL 存储账单与分类数据，开箱即用的默认分类可快速开始记账。
  • 📦 一键部署：提供 Docker 镜像与 docker-compose 编排，自动初始化数据库与字体资源。
  • 🧩 工具即服务：内置 get_categories 与 record_bill MCP Tool，可直接被任何兼容客户端调用。
  • 📈 中文环境友好：预置 fonts-noto-cjk，确保图表与报表在中文环境下无乱码。

🧱 技术栈总览

模块 技术 说明
服务框架 FastMCP 实现 MCP 服务端与工具暴露
数据访问 SQLAlchemy、PyMySQL ORM 管理模型，连接 MySQL
配置校验 Pydantic 保障配置、请求参数的合法性
部署 Docker、docker-compose 容器化部署与多服务编排

🚀 构建与部署指南

✅ 推荐：Docker Compose

  1. 克隆仓库
    git clone https://github.com/yourusername/mcp-finance-tracker.git
cd mcp-finance-tracker
  2. 启动服务
    docker-compose up -d
  3. 实时查看日志
    docker-compose logs -f mcp_server

首次启动会自动：

  • 创建 MySQL 数据库与所需表结构。
  • 写入默认分类（餐饮、交通、购物、收入）。
  • 安装中文字体以支持图表渲染。

🛠️ 本地运行 / 二次开发

  1. 准备环境：确保已安装 Python 3.11+ 与 MySQL。
  2. 安装依赖
    pip install -r requirements.txt
  3. 配置环境变量
    cp .env.example .env
# 编辑 .env 设置 DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME
  4. 启动 MySQL（可选）
    docker-compose up -d mysql
  5. 运行服务
    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 / expense
  • category_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

相关 MCP