佐霍MCP服务器

Name: 佐霍MCP服务器
Author: Mgabr90

作者：Mgabr902 星标更新：2025-07-26

安装使用来源：spider==github.com

项目介绍

Zoho CRM + Books MCP Server

一个统一的模型上下文协议（MCP）服务器，提供Zoho CRM与Zoho Books之间的无缝集成，使AI助手如Claude能够通过标准化工具和资源与这两个系统进行交互。

功能

CRM集成：完全访问Zoho CRM模块、记录和操作
Books集成：完整的Zoho Books客户和发票管理
数据同步：自动同步CRM账户和Books客户
发票创建：从CRM交易直接生成Books发票
通用搜索：跨CRM和Books数据搜索
多配置系统：管理不同环境和项目的多个OAuth配置
OAuth 2.0认证：安全的基于令牌的身份验证
速率限制：内置的速率限制和错误处理
TypeScript：完整的类型安全性及优秀的开发者体验

预备条件

Node.js 18.0.0或更高版本
具有API访问权限的Zoho CRM账户
具有API访问权限的Zoho Books账户
Zoho OAuth应用程序凭证

安装

克隆仓库：

git clone <repository-url>
cd zoho-mcp-server

安装依赖项：

npm install

复制环境配置：

cp .env.example .env

在.env中配置您的环境变量：

单一配置（旧版）

# Zoho OAuth配置
ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_REDIRECT_URI=http://localhost:3000/callback
ZOHO_REFRESH_TOKEN=your_refresh_token_here

# Zoho数据中心（com, eu, in, com.au, jp）
ZOHO_DATA_CENTER=com

# Zoho Books组织ID（用于Books功能）
ZOHO_BOOKS_ORGANIZATION_ID=your_organization_id_here

# Zoho API范围
ZOHO_SCOPES=ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoBooks.fullaccess.all

多配置系统（推荐）

# 启用多配置系统
MULTI_CONFIG_ENABLED=true

# 当前使用的环境
MULTI_CONFIG_ENVIRONMENT=default

# 配置文件路径（可选）
MULTI_CONFIG_PATH=./zoho-config.json

# 旧版变量（为了向后兼容）
ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_REDIRECT_URI=http://localhost:3000/callback
ZOHO_REFRESH_TOKEN=your_refresh_token_here
ZOHO_DATA_CENTER=com
ZOHO_BOOKS_ORGANIZATION_ID=your_organization_id_here
ZOHO_SCOPES=ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoBooks.fullaccess.all

关于详细的多配置设置，请参阅MULTI_CONFIG_GUIDE.md。

Zoho OAuth设置

访问Zoho开发者控制台
创建一个新的“基于服务器的应用程序”
将重定向URI设置为http://localhost:3000/callback
记录您的客户端ID和客户端密钥
使用授权流程生成刷新令牌

构建和运行

构建TypeScript代码：

npm run build

启动服务器：

npm start

对于带有自动重新加载的开发模式：

npm run dev

MCP集成

Claude桌面配置

在您的Claude桌面MCP配置中添加以下内容：

{
  "mcpServers": {
    "zoho-crm-books": {
      "command": "node",
      "args": ["C:\\zoho-mcp-server\\dist\\server.js"],
      "env": {
        "ZOHO_CLIENT_ID": "your_client_id",
        "ZOHO_CLIENT_SECRET": "your_client_secret",
        "ZOHO_REFRESH_TOKEN": "your_refresh_token",
        "ZOHO_DATA_CENTER": "com",
        "ZOHO_BOOKS_ORGANIZATION_ID": "your_org_id"
      }
    }
  }
}

VS Code配置

在您的VS Code MCP配置中添加以下内容：

{
  "servers": {
    "zoho-crm-books": {
      "command": "node",
      "args": ["C:\\zoho-mcp-server\\dist\\server.js"]
    }
  }
}

可用工具

CRM & Books集成工具

1. sync_accounts_to_customers

同步CRM账户到Books客户。

参数：

source_module: "accounts"（固定值）
target_module: "customers"（固定值）
filters（可选）：
- limit: 要处理的记录数（1-200）
- page: 要处理的页码

示例：

{
  "source_module": "accounts",
  "target_module": "customers",
  "filters": {
    "limit": 50,
    "page": 1
  }
}

1.1. sync_contacts_to_customers

同步CRM联系人到Books客户（双向同步）。

参数：

source_module: "contacts"（固定值）
target_module: "customers"（固定值）
filters（可选）：
- limit: 要处理的记录数（1-200）
- page: 要处理的页码

示例：

{
  "source_module": "contacts",
  "target_module": "customers",
  "filters": {
    "limit": 50,
    "page": 1
  }
}

1.2. sync_customers_to_contacts

同步Books客户到CRM联系人（双向同步）。

参数：

source_module: "customers"（固定值）
target_module: "contacts"（固定值）
filters（可选）：
- limit: 要处理的记录数（1-200）
- page: 要处理的页码

示例：

{
  "source_module": "customers",
  "target_module": "contacts",
  "filters": {
    "limit": 50,
    "page": 1
  }
}

2. create_invoice_from_deal

从CRM交易创建Books发票。

参数：

deal_id: CRM交易ID（必需）
customer_id: Books客户ID（可选）
invoice_date: 发票日期（可选，默认为今天）
due_date: 到期日（可选，默认为今天起30天）
include_line_items: 包含交易金额作为明细项（默认：true）
send_email: 发送发票电子邮件给客户（默认：false）

示例：

{
  "deal_id": "123456789",
  "customer_id": "987654321",
  "include_line_items": true,
  "send_email": true
}

3. search_records

跨CRM和Books记录搜索。

参数：

module: 要搜索的模块（"accounts", "contacts", "deals", "leads", "customers", "invoices"）
criteria: 搜索标准（必需）
fields: 要返回的字段（可选）
page: 页码（默认：1）
per_page: 每页结果数（默认：20，最大：200）

示例：

{
  "module": "accounts",
  "criteria": "科技公司",
  "fields": ["Account_Name", "Email", "Phone"],
  "page": 1,
  "per_page": 10
}

Books项目管理工具

4. books_get_items

获取Books中的所有项目，可选过滤和分页。

参数：

page: 页码（默认：1）
per_page: 每页结果数（默认：20，最大：200）
search_text: 搜索文本（可选）
filter_by: 过滤标准（可选）
sort_column: 排序列（可选）
sort_order: 排序顺序"A"或"D"（可选）

5. books_get_item

根据ID获取Books中的特定项目。

参数：

item_id: 项目ID（必需）

6. books_create_item

在Books中创建新项目。

参数：

name: 项目名称（必需）
description: 项目描述（可选）
rate: 项目费率（可选）
unit: 测量单位（可选）
sku: 库存单位（可选）
product_type: 产品类型（可选）
is_taxable: 是否征税（可选）
tax_id: 税务ID（可选）
item_type: 项目类型（可选）

7. books_update_item

更新Books中的现有项目。

参数：

item_id: 项目ID（必需）
加上要更新的books_create_item中的任何字段

8. books_delete_item

删除Books中的项目。

参数：

item_id: 项目ID（必需）

Books报价管理工具

9. books_get_estimates

获取Books中的所有报价，可选过滤和分页。

参数：

page: 页码（默认：1）
per_page: 每页结果数（默认：20，最大：200）
customer_id: 根据客户ID过滤（可选）
status: 根据状态过滤（可选）
search_text: 搜索文本（可选）
filter_by: 过滤标准（可选）
sort_column: 排序列（可选）
sort_order: 排序顺序"A"或"D"（可选）

10. books_create_estimate

在Books中创建新的报价。

参数：

customer_id: 客户ID（必需）
line_items: 明细项数组（必需）
- name: 项目名称（必需）
- quantity: 数量（必需）
- rate: 费率（必需）
- description: 描述（可选）
- unit: 单位（可选）
- item_id: 项目ID（可选）
- tax_id: 税务ID（可选）
estimate_date: 报价日期（可选）
expiry_date: 到期日期（可选）
currency_code: 货币代码（可选）
discount: 折扣金额（可选）
notes: 备注（可选）
terms: 条款（可选）

11. books_convert_estimate_to_invoice

将Books中的报价转换为发票。

参数：

estimate_id: 报价ID（必需）

Books付款管理工具

12. books_get_payments

获取Books中的所有付款，可选过滤和分页。

参数：

page: 页码（默认：1）
per_page: 每页结果数（默认：20，最大：200）
customer_id: 根据客户ID过滤（可选）
search_text: 搜索文本（可选）
filter_by: 过滤标准（可选）
sort_column: 排序列（可选）
sort_order: 排序顺序"A"或"D"（可选）

13. books_create_payment

在Books中创建新的付款。

参数：

customer_id: 客户ID（必需）
payment_mode: 付款方式（必需）
amount: 付款金额（必需）
date: 付款日期（必需）
invoices: 要应用付款的发票数组（必需）
- invoice_id: 发票ID（必需）
- invoice_number: 发票编号（必需）
- amount_applied: 应用于发票的金额（必需）
- tax_amount_withheld: 扣除的税额（可选）
reference_number: 参考编号（可选）
description: 付款描述（可选）
bank_charges: 银行费用（可选）
currency_code: 货币代码（可选）
exchange_rate: 汇率（可选）

CRM活动管理工具

14. crm_get_tasks

获取CRM中的所有任务，可选过滤和分页。

参数：

page: 页码（默认：1）
per_page: 每页结果数（默认：20，最大：200）
sort_by: 排序列（可选）
sort_order: 排序顺序"asc"或"desc"（可选）
status: 根据状态过滤（可选）
due_date: 根据到期日期过滤（可选）

15. crm_create_task

在CRM中创建新的任务。

参数：

Subject: 任务主题（必需）
Status: 任务状态（可选）
Priority: 任务优先级（可选）
Due_Date: 到期日期（可选）
What_Id: 相关记录ID（可选）
Who_Id: 联系人ID（可选）
Description: 任务描述（可选）
Related_To: 相关字段（可选）
Remind_At: 提醒时间（可选）
Recurring_Activity: 周期性活动设置（可选）

16. crm_get_events

获取CRM中的所有事件，可选过滤和分页。

参数：

page: 页码（默认：1）
per_page: 每页结果数（默认：20，最大：200）
sort_by: 排序列（可选）
sort_order: 排序顺序"asc"或"desc"（可选）
start_date: 根据开始日期过滤（可选）
end_date: 根据结束日期过滤（可选）

17. crm_create_event

在CRM中创建新的事件。

参数：

Subject: 事件主题（必需）
Start_DateTime: 开始日期和时间（必需）
End_DateTime: 结束日期和时间（必需）
Description: 事件描述（可选）
Location: 事件地点（可选）
What_Id: 相关记录ID（可选）
Who_Id: 联系人ID（可选）
Event_Title: 事件标题（可选）
All_day: 整天事件标志（可选）
Participants: 参与者ID数组（可选）
Remind_At: 提醒时间（可选）
Recurring_Activity: 周期性活动设置（可选）

18. crm_get_notes

获取特定CRM记录的笔记。

参数：

module: CRM模块名称（必需）
record_id: 记录ID（必需）
page: 页码（默认：1）
per_page: 每页结果数（默认：20，最大：200）

19. crm_create_note

为CRM记录创建新的笔记。

参数：

module: CRM模块名称（必需）
record_id: 记录ID（必需）
Note_Title: 笔记标题（必需）
Note_Content: 笔记内容（必需）
Parent_Id: 父记录ID（可选）

20. crm_send_email

发送CRM记录的电子邮件。

参数：

module: CRM模块名称（必需）
record_id: 记录ID（必需）
to: 收件人电子邮件地址数组（必需）
subject: 邮件主题（必需）
content: 邮件内容（必需）
cc: 抄送电子邮件地址数组（可选）
bcc: 密送电子邮件地址数组（可选）
mail_format: 邮件格式（可选）
template_id: 邮件模板ID（可选）

21. crm_get_attachments

获取CRM记录的附件。

参数：

module: CRM模块名称（必需）
record_id: 记录ID（必需）
page: 页码（默认：1）
per_page: 每页结果数（默认：20，最大：200）

配置管理工具

22. config_list_environments

列出多配置系统中的所有可用环境。

参数： 无

示例：

{
  "name": "config_list_environments",
  "arguments": {}
}

23. config_switch_environment

切换到不同的环境。

参数：

environmentName: 要切换到的环境名称（必需）

示例：

{
  "name": "config_switch_environment",
  "arguments": {
    "environmentName": "production"
  }
}

24. config_list_profiles

列出当前环境中的所有配置文件。

参数： 无

示例：

{
  "name": "config_list_profiles",
  "arguments": {}
}

25. config_switch_profile

在当前环境中切换到不同的配置文件。

参数：

profileName: 要切换到的配置文件名称（必需）

示例：

{
  "name": "config_switch_profile",
  "arguments": {
    "profileName": "backup"
  }
}

26. config_add_profile

向当前环境添加新的配置文件。

参数：

name: 配置文件名称（必需）
description: