Accounting MCP Server

记账 MCP 工具演示项目

基于 Model Context Protocol (MCP) 的个人记账管理工具，为 AI 助手提供财务管理功能。

项目概述

这是一个学习和演示 MCP 协议开发的项目，通过构建实用的记账工具来深入理解：

MCP Tools 和 Resources 的设计模式
JSON-RPC 协议在 AI 工具开发中的应用
TDD 驱动的高质量代码开发流程
AI 助手与外部工具的标准化集成方式

功能特性

MCP Tools（AI 可调用的工具）

add_transaction - 添加收支记录
get_balance - 查询账户余额
list_transactions - 查询交易记录（支持筛选）
get_monthly_summary - 获取月度财务汇总

MCP Resources（AI 可访问的数据）

transactions://all - 所有交易记录
categories://list - 支出分类列表
summary://current - 账户汇总信息

快速开始

环境要求

Python 3.11+
conda（推荐）或 uv/pip

安装依赖

方案 1: 使用 conda + uv（推荐，最快）

# 激活您的 conda 环境
conda activate myenv

# 使用 uv 快速安装依赖
uv pip install -r requirements.txt
uv pip install -r requirements-dev.txt

方案 2: 纯 conda

# 激活环境
conda activate myenv

# 安装 Python 依赖
pip install -r requirements.txt
pip install -r requirements-dev.txt

方案 3: 纯虚拟环境

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # macOS/Linux

# 安装依赖  
pip install -r requirements.txt
pip install -r requirements-dev.txt

运行服务器

# 直接运行 MCP 服务器
python -m accounting_mcp.server

# 或者运行交互式测试客户端
python test_client.py

测试示例

# 添加一笔支出
echo '{"jsonrpc":"2.0","method":"add_transaction","params":{"amount":-50,"category":"food","description":"午餐"},"id":1}' | python -m accounting_mcp.server

# 查询余额
echo '{"jsonrpc":"2.0","method":"get_balance","params":{},"id":2}' | python -m accounting_mcp.server

项目结构

accounting-mcp-demo/
├── accounting_mcp/          # 核心代码
│   ├── __init__.py         # 包初始化
│   ├── server.py           # MCP 服务器主程序  
│   ├── models.py           # 数据模型定义
│   ├── storage.py          # JSON 文件存储
│   └── tools.py            # MCP 工具实现
├── tests/                   # 测试代码
│   ├── test_models.py      # 模型测试
│   ├── test_storage.py     # 存储测试
│   ├── test_tools.py       # 工具测试
│   └── test_server.py      # 服务器测试
├── data/                    # 数据文件
│   ├── transactions.json   # 交易记录
│   ├── account.json        # 账户信息
│   └── categories.json     # 分类定义
├── docs/                    # 文档
├── PRD.md                   # 产品需求文档
├── TDD_PLAN.md             # TDD 开发计划
├── requirements.txt         # 项目依赖
├── requirements-dev.txt     # 开发依赖
└── test_client.py          # 交互测试客户端

开发指南

TDD 开发流程

本项目采用测试驱动开发（TDD），遵循"红-绿-重构"循环：

红阶段: 先写失败的测试用例
绿阶段: 编写最小实现使测试通过
重构阶段: 优化代码质量和结构

运行测试

# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_models.py

# 生成覆盖率报告
pytest --cov=accounting_mcp --cov-report=html

# 类型检查
mypy accounting_mcp/

代码质量检查

# 格式化代码
black accounting_mcp/ tests/

# 风格检查
flake8 accounting_mcp/ tests/

# 运行所有质量检查
pre-commit run --all-files

MCP 集成

Claude Desktop 配置

在 Claude Desktop 的配置文件中添加：

{
  "mcpServers": {
    "accounting": {
      "command": "python",
      "args": ["/path/to/accounting-mcp-demo/accounting_mcp/server.py"],
      "env": {}
    }
  }
}

使用示例

配置完成后，可以通过自然语言与 AI 助手交互：

用户: "帮我记录一笔35元的午餐费用"
Claude: 已为您添加35元的餐饮支出，当前余额为1,965元。

用户: "我这个月在食物上花了多少钱？"
Claude: 根据记录，您本月在餐饮分类上总计支出285元。

技术架构

MCP 协议实现

传输层: stdio（标准输入输出）
协议层: JSON-RPC 2.0
应用层: 工具注册和资源管理

数据存储

轻量级 JSON 文件存储
支持事务性操作
自动备份和恢复

错误处理

完善的输入验证
优雅的错误恢复
详细的错误日志

扩展和定制

添加新的工具

在 tools.py 中定义新的工具函数
在 server.py 中注册工具
编写对应的测试用例

自定义分类

修改 data/categories.json 文件，添加自定义的支出分类。

数据导入导出

未来版本将支持 CSV 格式的数据导入导出功能。

许可证

本项目仅用于学习和演示目的，基于 MIT 许可证开源。

贡献

欢迎提交 Issues 和 Pull Requests 来改进项目。

构建于 MCP 1.0 协议之上，遵循最佳实践和 TDD 开发原则。

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables personal financial management through AI assistants by providing tools to add transactions, check balances, list transaction history, and generate monthly summaries. Supports natural language interaction for tracking income and expenses with categorization.

Related MCP Servers

Portfolio Manager
ikhyunAn
-
security
F
license
-
quality
Enables users to create, manage, and analyze investment portfolios with real-time market data, personalized recommendations, and visual representations of asset allocation.
Last updated -
3
Financial Modeling Prep MCP Server
imbenrabi
A
security
A
license
A
quality
Enables AI assistants to access and analyze financial data including stock information, company fundamentals, and market insights through the Financial Modeling Prep API.
Last updated -
126
42
TypeScript
Apache 2.0
You Need A Budget (YNAB) MCP
Jtewen
A
security
A
license
A
quality
An MCP to give AI agents extensive knowledge of your personal finances and control of your budgeting.
Last updated -
14
3
MIT License
freee会計 MCP Server
tsurutan
-
security
A
license
-
quality
Enables AI assistants to access and manage accounting data through the freee accounting API, supporting operations like transaction management, financial analysis, and account item management.
Last updated -
620
1
MIT License

View all related MCP servers