Zoho簿记员MCP服务器
A. 模型上下文协议（MCP） Zoho Books集成服务器，专为使用AI代理的簿记工作流程而设计。
为什么存在
官方的Zoho MCP服务（zohomcp.com）有局限性：
- 无法上传文件附件 -MCP架构将二进制文件参数错误地映射为查询字符串
- 工具太多 -100+工具快速耗尽AI工具限制
- 刀具选择难以控制 -mcp.zoho.com界面很麻烦，代理无法使用
此自定义MCP服务器提供：
- 正确上传附件的多部分/表单数据文件
- 一套49个簿记工作流程工具
- 自动刷新OAuth令牌（1小时生命周期，5分钟缓冲）
- stdio（CLI）和HTTP流传输
特性
- 完整的CRUD操作 用于日记账、费用、账单和发票
- 文件附件 具有适当的多部分上传支持（PDF、图像、Office文档）
- 会计科目表 管理和事务查询
- 银行账户 整合与交易列表
- 联系人管理 面向客户和供应商
- OAuth 2.0 具有自动令牌刷新功能
- 健康检查 用于容器编排
可用工具（共49个）
| 类别 | 工具 | 描述 |
|---|---|---|
| 组织 | 2 | 列出组织，获取组织详细信息 |
| 会计科目表 | 4 | 列出/获取/创建帐户，列出交易 |
| 期刊 | 9 | 完整CRUD+发布+附件 |
| 开支 | 6 | 完整的CRUD+收据附件 |
| 账单 | 6 | 完整的CRUD+附件 |
| 发票 | 5 | 列表/获取+附件 |
| 联系人 | 2 | 列出/获取客户和供应商 |
| 供应商 | 4 | 供应商特定列表/获取/创建/更新工作流 |
| 银行账户 | 11 | 列出账户/交易+匹配+分类工作流程 |
先决条件
- Node.js 20+
- 拥有API访问权限的Zoho Books帐户
- Zoho OAuth 2.0凭据（请参阅 配置)
安装
选项1：使用npx运行（建议用于桌面代理）
npx zoho-bookkeeper-mcp选项2：全局安装
npm install -g zoho-bookkeeper-mcp
zoho-bookkeeper-mcp选项3:Docker
docker build -t zoho-bookkeeper-mcp .
docker run -p 8004:8004 \
-e ZOHO_CLIENT_ID=your_client_id \
-e ZOHO_CLIENT_SECRET=your_client_secret \
-e ZOHO_REFRESH_TOKEN=your_refresh_token \
zoho-bookkeeper-mcp选项4：来源
git clone https://github.com/bu5hm4nn/zoho-bookkeeper-mcp.git
cd zoho-bookkeeper-mcp
pnpm install
pnpm build配置
运行交互式安装程序：
pnpm setup这将指导您完成：
- 创建Zoho自助客户端应用程序
- 输入您的客户ID和密码
- 生成和交换授权码
- 将凭据保存到
.env
手动配置
如果您更喜欢手动设置，请复制 .env.example 到 .env 并遵循 Zoho OAuth文档 以获得：
ZOHO_CLIENT_ID-从Zoho API控制台ZOHO_CLIENT_SECRET-从Zoho API控制台ZOHO_REFRESH_TOKEN-通过具有作用域的OAuth授权代码流获得ZohoBooks.fullaccess.all
环境变量
这 .env 文件应包含：
# Required
ZOHO_CLIENT_ID=1000.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ZOHO_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ZOHO_REFRESH_TOKEN=1000.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Optional
ZOHO_API_URL=https://www.zohoapis.com/books/v3 # Default (US datacenter)
ZOHO_ORGANIZATION_ID=123456789 # Default org ID (optional)
PORT=8004 # HTTP server port
HOST=0.0.0.0 # HTTP server hostAPI地区网址：
- 美国（默认）：
https://www.zohoapis.com/books/v3 - 欧盟：
https://www.zohoapis.eu/books/v3 - 在……里面
https://www.zohoapis.in/books/v3 - AU：
https://www.zohoapis.com.au/books/v3
与聊天代理集成
克劳德桌面版
添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"zoho-bookkeeper": {
"command": "npx",
"args": ["zoho-bookkeeper-mcp"],
"env": {
"ZOHO_CLIENT_ID": "your_client_id",
"ZOHO_CLIENT_SECRET": "your_client_secret",
"ZOHO_REFRESH_TOKEN": "your_refresh_token"
}
}
}
}或者，如果全局安装：
{
"mcpServers": {
"zoho-bookkeeper": {
"command": "zoho-bookkeeper-mcp",
"env": {
"ZOHO_CLIENT_ID": "your_client_id",
"ZOHO_CLIENT_SECRET": "your_client_secret",
"ZOHO_REFRESH_TOKEN": "your_refresh_token"
}
}
}
}Librechat
添加到您的 librechat.yaml:
mcpServers:
zoho-bookkeeper:
type: streamable-http
url: http://mcp-zoho-bookkeeper:8004/mcp
timeout: 30000和你的 docker-compose.yml:
services:
mcp-zoho-bookkeeper:
build:
context: ./path/to/zoho-bookkeeper-mcp
container_name: mcp-zoho-bookkeeper
restart: unless-stopped
environment:
PORT: 8004
ZOHO_CLIENT_ID: ${ZOHO_CLIENT_ID}
ZOHO_CLIENT_SECRET: ${ZOHO_CLIENT_SECRET}
ZOHO_REFRESH_TOKEN: ${ZOHO_REFRESH_TOKEN}
ports:
- "8004:8004"
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8004/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 30s通用MCP客户端（HTTP）
启动HTTP服务器：
# Using pnpm
pnpm serve
# Or directly
node dist/server.js连接到 http://localhost:8004/mcp 使用流式http传输。
通用MCP客户端（stdio）
# Using pnpm
pnpm start
# Or directly
node dist/bin.js使用示例
获取组织ID（第一步必填）
大多数工具都需要 organization_id.先得到它：
Use the list_organizations tool to get your Zoho organization ID创建日记条目
Create a journal entry dated 2025-01-15 with:
- Debit Office Supplies (account_id: 123456) for $150
- Credit Business Checking (account_id: 789012) for $150
Reference: "Office supplies purchase"附上收据
Upload the file /path/to/receipt.pdf to journal 4567890123456列出最近的支出
List all expenses from the last 30 days发展
设置
git clone https://github.com/bu5hm4nn/zoho-bookkeeper-mcp.git
cd zoho-bookkeeper-mcp
pnpm install命令
pnpm build # Build TypeScript to dist/
pnpm dev # Run with hot reload (HTTP server)
pnpm serve:dev # Same as dev
pnpm start # Run stdio transport
pnpm serve # Run HTTP server
pnpm test # Run all tests
pnpm test:unit # Run unit tests only
pnpm test:watch # Run tests in watch mode
pnpm test:coverage # Run tests with coverage
pnpm lint # Check for linting errors
pnpm lint:fix # Fix linting errors
pnpm format # Format code with Prettier
pnpm format:check # Check formatting项目结构
zoho-bookkeeper-mcp/
├── src/
│ ├── index.ts # Main MCP server setup
│ ├── server.ts # HTTP server entry point
│ ├── bin.ts # CLI entry point (stdio)
│ ├── config.ts # Configuration management
│ ├── api/
│ │ ├── client.ts # Zoho API client helpers
│ │ └── types.ts # TypeScript type definitions
│ ├── auth/
│ │ └── oauth.ts # OAuth token management
│ ├── tools/
│ │ ├── organizations.ts
│ │ ├── chart-of-accounts.ts
│ │ ├── journals.ts
│ │ ├── expenses.ts
│ │ ├── bills.ts
│ │ ├── invoices.ts
│ │ ├── contacts.ts
│ │ └── bank-accounts.ts
│ ├── utils/
│ │ ├── errors.ts
│ │ ├── mime-types.ts
│ │ └── response-parser.ts
│ └── __tests__/ # Test files
├── dist/ # Compiled JavaScript
├── Dockerfile
├── package.json
└── tsconfig.jsonAPI终点
作为HTTP服务器运行时：
| 端点 | 描述 |
|---|---|
GET /health | 健康检查（返回JSON状态） |
POST /mcp | MCP协议端点（可流式传输http） |
故障排除
“OAuth令牌无效”错误
- 验证您的刷新令牌是否有效
- 检查您的Zoho应用程序是否具有
ZohoBooks.fullaccess.all范围 - 确保设置了正确的区域API URL
“找不到组织”错误
- 使用
list_organizations首先获取有效的组织ID - 集
ZOHO_ORGANIZATION_ID默认组织的env-var
附件上传失败
- 验证服务器是否可以访问文件路径
- 检查是否支持文件类型（PDF、PNG、JPG、GIF、DOC、DOCX、XLS、XLSX）
- 确保文件大小在Zoho的限制范围内
速率限制
此服务器每次请求使用约3k个令牌，而托管的Zoho MCP（100+个工具）使用约30k个令牌。如果仍然达到速率限制，请在请求之间添加延迟。
技术栈
- 运行时：Node.js 20+
- 框架: FastMCP
- 语言：TypeScript
- 认证：OAuth 2.0，带有刷新令牌流
- 构建：tsup
- 测试：Vitest
- 掉毛：ESLint+Prettier
许可证
MIT许可证-请参阅 许可证 了解详情。
贡献
欢迎投稿！请打开问题或提交拉取请求。