Zoho Bookkeeper MCP

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个）

先决条件

• 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

这将指导您完成：

1. 创建Zoho自助客户端应用程序
2. 输入您的客户ID和密码
3. 生成和交换授权码
4. 将凭据保存到 .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 host

API地区网址：

• 美国（默认）： 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.json

API终点

作为HTTP服务器运行时：

故障排除

“OAuth令牌无效”错误

1. 验证您的刷新令牌是否有效
2. 检查您的Zoho应用程序是否具有 ZohoBooks.fullaccess.all 范围
3. 确保设置了正确的区域API URL

“找不到组织”错误

1. 使用 list_organizations 首先获取有效的组织ID
2. 集 ZOHO_ORGANIZATION_ID 默认组织的env-var

附件上传失败

1. 验证服务器是否可以访问文件路径
2. 检查是否支持文件类型（PDF、PNG、JPG、GIF、DOC、DOCX、XLS、XLSX）
3. 确保文件大小在Zoho的限制范围内

速率限制

此服务器每次请求使用约3k个令牌，而托管的Zoho MCP（100+个工具）使用约30k个令牌。如果仍然达到速率限制，请在请求之间添加延迟。

技术栈

• 运行时：Node.js 20+
• 框架: FastMCP
• 语言：TypeScript
• 认证：OAuth 2.0，带有刷新令牌流
• 构建：tsup
• 测试：Vitest
• 掉毛：ESLint+Prettier

许可证

MIT许可证-请参阅 许可证 了解详情。

贡献

欢迎投稿！请打开问题或提交拉取请求。

相关项目

• 模型上下文协议 -协议规范
• FastMCP -此服务器使用的MCP框架
• Zoho图书API -Zoho Books API官方文档