佐霍MCP服务器
项目介绍
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: