EzBookkeeping MCP服务器
  
一个全面的模型上下文协议（MCP）服务器，将AI助手与 Ez记账，实现个人财务管理的自然语言交互。
注： 该项目目前正在积极开发中。服务器当前包含示例/演示实现。根据此存储库中记录的全面研究，计划与EzBookkeeping API完全集成。
这是什么？
此MCP服务器允许像Claude这样的AI助手通过自然语言与您的EzBookkeeping实例进行交互。让克劳德通过对话添加交易、检查余额、分析支出模式并生成财务报告。
交互示例：
- “在我的支票账户中增加45美元的杂货费”
- “显示我本月的支出趋势”
- “我所有账户的总余额是多少？”
- “创建上一季度的预算报告”
特性
当前（演示实现）
工具（写入操作）：
add_transaction-添加收入或支出交易calculate_balance-根据交易列表计算余额
资源（读取操作）：
bookkeeping://summary/{period}-获取一段时间的财务摘要
提示（AI模板）：
create_financial_report-生成财务报告提示
计划中（全面EzBookkeeping集成）
根据API的全面研究（记录了99个终点）：
交易管理：
- 创建、更新、删除交易
- 批量操作
- 人工智能收据识别
- 交易统计和趋势
- 导入/导出功能
账户管理：
- 管理9种类型的账户（现金、信用卡、投资等）
- 多币种支持
- 具有子账户的分层账户
组织机构：
- 类别和标签管理
- 交易模板
- 经常性交易
分析：
- 支出分析和趋势
- 预算跟踪
- 财务摘要和报告
看 MCP_SERVER_DESIGN.md 完整的架构计划。
安装
先决条件
- Python 3.10或更高版本
- 紫外线 包管理器
- （可选）用于API完全集成的EzBookkeeping实例
快速开始
- 克隆存储库：
git clone https://github.com/theanirudhvyas/ezbookkeeping_mcp_server.git
cd ezbookkeeping_mcp_server- 安装依赖项：
uv sync- 配置（用于完整的EzBookkeeping集成）：
cp .env.example .env
# Edit .env with your EzBookkeeping instance URL and API token- 测试服务器：
uv run mcp dev main.py这将打开MCP检查器 http://localhost:5173 用于交互式测试。
配置
对于完整的EzBookkeeping API集成，请配置以下环境变量：
# Required
EZBOOKKEEPING_URL=https://your-instance.com
EZBOOKKEEPING_TOKEN=your_api_token_here
# Optional
EZBOOKKEEPING_TIMEZONE_OFFSET=0
EZBOOKKEEPING_DEFAULT_CURRENCY=USD看 .env.example 获取完整的配置模板。
使用Claude Desktop
自动安装
uv run mcp install main.py手动配置
添加到您的Claude Desktop配置文件中：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"ezbookkeeping": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/ezbookkeeping_mcp_server",
"run",
"mcp",
"run",
"main.py"
],
"env": {
"EZBOOKKEEPING_URL": "https://your-instance.com",
"EZBOOKKEEPING_TOKEN": "your_token"
}
}
}
}重新启动Claude Desktop以加载服务器。
发展
运行MCP检查器
MCP检查器提供了一个交互式web界面用于测试：
uv run mcp dev main.py开放时间： http://localhost:5173 与：
- 使用参数表进行工具测试
- 资源浏览
- 快速生成
- 实时请求/响应日志
运行测试
# Install dev dependencies
uv sync --all-extras
# Run tests
uv run pytest
# Run with coverage
uv run pytest --cov=. --cov-report=html使用示例
添加交易
# Using the add_transaction tool
add_transaction(
amount=50.00,
description="Grocery shopping",
category="food",
transaction_type="expense"
)计算余额
# Using the calculate_balance tool
transactions = [
{"amount": 1000, "type": "income"},
{"amount": 50, "type": "expense"},
{"amount": 30, "type": "expense"}
]
calculate_balance(transactions)
# Returns: {"income": 1000, "expenses": 80, "balance": 920}获取摘要
访问资源URI：
bookkeeping://summary/month项目结构
ezbookkeeping_mcp_server/
├── main.py # MCP server implementation
├── pyproject.toml # Project configuration & dependencies
├── API_DOCUMENTATION.md # Complete EzBookkeeping API reference (99 endpoints)
├── MCP_SERVER_DESIGN.md # Architecture and implementation plan
├── QUICKSTART.md # Quick reference guide
├── README.md # This file
├── CONTRIBUTING.md # Contribution guidelines
├── CHANGELOG.md # Version history
├── LICENSE # MIT License
├── .env.example # Environment configuration template
├── .claude/ # Claude Code configuration
│ └── CLAUDE.md # MCP development best practices
├── tests/ # Test suite (planned)
└── .venv/ # Virtual environment (gitignored)文档
- API_DOCUMENTATION.md -完成所有99个端点的EzBookkeeping API参考
- MCP_SERVER_DESIGN.md -全面的架构、设计决策和路线图
- QUICKSTART.md -常见操作快速入门指南
- .claude/claude.md -MCP服务器开发最佳实践
路线图
第一阶段：基础（计划中）
- \[\]具有身份验证的HTTP客户端
- \[\]令牌管理和刷新
- \[\]错误处理和重试逻辑
- \[\]时区支持
第2阶段：核心功能（计划中）
- \[\]交易工具（添加、更新、删除）
- \[\]帐户资源（列表、获取）
- \[\]交易资源（列表、统计）
- \[\]类别/标签资源
第3阶段：高级功能（计划中）
- \[\]批量操作
- \[\]交易模板
- \[\]人工智能收据识别集成
- \[\]导出功能
- \[\]汇率管理
第四阶段：情报（计划中）
- \[\]支出分析提示
- \[\]预算跟踪提示
- \[\]生成财务见解
- \[\]重复检测
- \[\]类别建议
看 MCP_SERVER_DESIGN.md 详细的实施计划。
贡献
欢迎投稿！请看 贡献.md 作为指导方针。
贡献领域
- 实现API端点
- 添加测试
- 改进错误处理
- 文档改进
- 功能建议
支持
- 问题：
- 讨论：
- Ez记账： 官方文件
相关项目
- Ez记账 -个人簿记应用程序
- 模型上下文协议 -MCP规范和文件
- Python MCP SDK -官方Python SDK
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
致谢
- 模型上下文协议 Anthropic为整合框架
- MCP工具和资源社区
免责声明
该项目与EzBookkeeping项目没有正式关联或认可。它是使用EzBookkeeping的公共HTTP API构建的独立集成。