Zoho CRM+图书MCP服务器
一个统一的模型上下文协议（MCP）服务器，提供Zoho CRM和Zoho Books之间的无缝集成，使像Claude这样的人工智能助手能够通过标准化的工具和资源与这两个系统进行交互。
特性
- CRM集成：完全访问Zoho CRM模块、记录和操作
- 图书集成：完成Zoho Books客户和发票管理
- 数据同步：CRM帐户和图书客户之间的自动同步
- 发票创建：直接从CRM交易生成图书发票
- 通用搜索：在CRM和图书数据中搜索
- 多配置系统：管理不同环境和项目的多个OAuth配置
- OAuth 2.0身份验证：安全的、基于令牌的身份验证
- 速率限制：内置速率限制和错误处理
- TypeScript：全类型安全和出色的开发人员体验
先决条件
- Node.js 18.0.0或更高版本
- 具有API访问权限的Zoho CRM帐户
- 拥有API访问权限的Zoho Books帐户
- Zoho OAuth应用程序凭据
安装
- 克隆存储库：
git clone
cd zoho-mcp-server- 安装依赖项：
npm install- 复制环境配置：
cp .env.example .env- 在中配置环境变量
.env:
单一配置（传统）
# Zoho OAuth Configuration
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, eu, in, com.au, jp)
ZOHO_DATA_CENTER=com
# Zoho Books Organization ID (required for Books functionality)
ZOHO_BOOKS_ORGANIZATION_ID=your_organization_id_here
# Zoho API Scopes
ZOHO_SCOPES=ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoBooks.fullaccess.all多配置系统（推荐）
# Enable multi-configuration system
MULTI_CONFIG_ENABLED=true
# Current environment to use
MULTI_CONFIG_ENVIRONMENT=default
# Path to configuration file (optional)
MULTI_CONFIG_PATH=./zoho-config.json
# Legacy variables (for backward compatibility)
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 devMCP集成
Claude桌面配置
将以下内容添加到您的Claude Desktop 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代码配置
添加到您的VS代码MCP配置中：
{
"servers": {
"zoho-crm-books": {
"command": "node",
"args": ["C:\\zoho-mcp-server\\dist\\server.js"]
}
}
}可用工具
CRM和图书集成工具
1.向客户同步计数
将CRM帐户与图书客户同步。
参数：
source_module：“账户”（固定）target_module：“客户”（固定）filters（可选）：
- limit：要处理的记录数（1-200） - page：要处理的页码
例子：
{
"source_module": "accounts",
"target_module": "customers",
"filters": {
"limit": 50,
"page": 1
}
}1.1.sync_contacts_to_客户
将CRM联系人同步到图书客户（双向同步）。
参数：
source_module：“联系人”（固定）target_module：“客户”（固定）filters（可选）：
- limit：要处理的记录数（1-200） - page：要处理的页码
例子：
{
"source_module": "contacts",
"target_module": "customers",
"filters": {
"limit": 50,
"page": 1
}
}1.2.sync_customers_to_ctacts
将图书客户与CRM联系人同步（双向同步）。
参数：
source_module：“客户”（固定）target_module：“联系人”（固定）filters（可选）：
- limit：要处理的记录数（1-200） - page：要处理的页码
例子：
{
"source_module": "customers",
"target_module": "contacts",
"filters": {
"limit": 50,
"page": 1
}
}2.create_invoice_from_deal
根据CRM交易创建图书发票。
参数：
deal_id：CRM交易ID（必填）customer_id：书籍客户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.搜索记录
在CRM和图书记录中搜索。
参数：
module：搜索模块（“账户”、“联系人”、“交易”、“线索”、“客户”、“发票”）criteria：搜索条件（必填）fields：要返回的字段（可选）page：页码（默认值：1）per_page：每页结果数（默认值：20，最大值：200）
例子：
{
"module": "accounts",
"criteria": "tech company",
"fields": ["Account_Name", "Email", "Phone"],
"page": 1,
"per_page": 10
}图书项目管理工具
4.书籍_物品
通过可选的筛选和分页从图书中获取所有项目。
参数：
page：页码（默认值：1）per_page：每页结果数（默认值：20，最大值：200）search_text：搜索文本（可选）filter_by：筛选条件（可选）sort_column：排序依据的列（可选）sort_order：排序顺序“A”或“D”（可选）
5.书籍_物品
按ID从图书中获取特定项目。
参数：
item_id：项目ID（必填）
6.书籍_创建_项目
在书籍中创建新项目。
参数：
name：项目名称（必填）description：项目描述（可选）rate：项目费率（可选）unit：计量单位（可选）sku：库存单位（可选）product_type：产品类型（可选）is_taxable：项目是否应纳税（可选）tax_id：税号（可选）item_type：项目类型（可选）
7.书籍_更新_项目
更新图书中的现有项目。
参数：
item_id：项目ID（必填）- 加上以下任何字段
books_create_item更新
8.书籍_删除_项目
从书籍中删除项目。
参数：
item_id：项目ID（必填）
图书估价管理工具
9.书籍_估算
通过可选的过滤和分页功能从图书中获取所有估计值。
参数：
page：页码（默认值：1）per_page：每页结果数（默认值：20，最大值：200）customer_id：按客户ID筛选（可选）status：按状态筛选（可选）search_text：搜索文本（可选）filter_by：筛选条件（可选）sort_column：排序依据的列（可选）sort_order：排序顺序“A”或“D”（可选）
10.书籍_创造_估计
在图书中创建新的估算。
参数：
customer_id：客户ID（必填）line_items：行项目数组（必填）
- name：项目名称（必填） - quantity：数量（必填） - rate：费率（必填） - description：描述（可选） - unit：单位（可选） - item_id：项目ID（可选） - tax_id：税号（可选）
estimate_date：估计日期（可选）expiry_date：到期日期（可选）currency_code：货币代码（可选）discount：折扣金额（可选）notes：备注（可选）terms：条款（可选）
11.书籍_转换_估算_转语音
将图书估价转换为发票。
参数：
estimate_id：估算ID（必填）
图书付款管理工具
12.书籍_付款
通过可选的过滤和分页功能从图书中获取所有付款。
参数：
page：页码（默认值：1）per_page：每页结果数（默认值：20，最大值：200）customer_id：按客户ID筛选（可选）search_text：搜索文本（可选）filter_by：筛选条件（可选）sort_column：排序依据的列（可选）sort_order：排序顺序“A”或“D”（可选）
13.书籍_创建_付款
在图书中创建新付款。
参数：
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：CC电子邮件地址数组（可选）bcc：BCC电子邮件地址数组（可选）mail_format：电子邮件格式（可选）template_id：电子邮件模板ID（可选）
21.crm_get_attachments
获取CRM记录的附件。
参数：
module：CRM模块名称（必填）record_id：记录ID（必填）page：页码（默认值：1）per_page：每页结果数（默认值：20，最大值：200）
配置管理工具
22.配置列表环境
列出多配置系统中的所有可用环境。
参数： 无
例子：
{
"name": "config_list_environments",
"arguments": {}
}23.配置开关环境
切换到其他环境。
参数：
environmentName：要切换到的环境名称（必需）
例子：
{
"name": "config_switch_environment",
"arguments": {
"environmentName": "production"
}
}24.配置列表文件
列出当前环境中的所有配置文件。
参数： 无
例子：
{
"name": "config_list_profiles",
"arguments": {}
}25.配置开关文件
在当前环境中切换到其他配置文件。
参数：
profileName：要切换到的配置文件的名称（必需）
例子：
{
"name": "config_switch_profile",
"arguments": {
"profileName": "backup"
}
}26.配置_添加_文件
将新配置文件添加到当前环境中。
参数：
name：配置文件名称（必填）description：配置文件描述（可选）clientId：Zoho客户端ID（必填）clientSecret：Zoho客户端密码（必填）redirectUri：重定向URI（必需）refreshToken：刷新令牌（必需）dataCenter：数据中心（必填）scopes：API作用域数组（必需）organizationId：图书组织ID（可选）
例子：
{
"name": "config_add_profile",
"arguments": {
"name": "backup",
"description": "Backup production account",
"clientId": "1000.BACKUP_CLIENT_ID",
"clientSecret": "BACKUP_CLIENT_SECRET",
"redirectUri": "https://yourdomain.com/callback",
"refreshToken": "1000.BACKUP_REFRESH_TOKEN",
"dataCenter": "com",
"scopes": [
"ZohoCRM.modules.ALL",
"ZohoCRM.settings.ALL",
"ZohoBooks.fullaccess.all"
],
"organizationId": "BACKUP_ORG_ID"
}
}27.config_remove_file
从当前环境中删除配置文件。
参数：
profileName：要删除的配置文件的名称（必需）
例子：
{
"name": "config_remove_profile",
"arguments": {
"profileName": "old-profile"
}
}28.配置更新文件
更新现有配置文件。
参数：
profileName：要更新的配置文件的名称（必需）updates：包含要更新的字段的对象（必需）
例子：
{
"name": "config_update_profile",
"arguments": {
"profileName": "primary",
"updates": {
"description": "Updated description",
"refreshToken": "1000.NEW_REFRESH_TOKEN"
}
}
}29.配置_获取_状态
获取当前配置状态。
参数： 无
例子：
{
"name": "config_get_status",
"arguments": {}
}30.配置导出环境
将当前配置导出为.env格式。
参数：
profileName：要导出的配置文件的名称（可选，默认为活动配置文件）
例子：
{
"name": "config_export_to_env",
"arguments": {
"profileName": "primary"
}
}31.config_add_environment
添加新环境。
参数：
name：环境名称（必填）description：环境描述（可选）
例子：
{
"name": "config_add_environment",
"arguments": {
"name": "staging",
"description": "Staging environment for testing"
}
}32.配置移除环境
删除环境。
参数：
name：要删除的环境名称（必填）
例子：
{
"name": "config_remove_environment",
"arguments": {
"name": "old-environment"
}
}可用资源
1.zoho://crm/modules
返回所有可用的CRM模块及其配置。
2.zoho://books/organizations
返回图书组织信息。
使用示例
Claude桌面集成
配置后，您可以将服务器与Claude Desktop一起使用：
@zoho-crm-books sync_accounts_to_customers with limit 10
@zoho-crm-books create_invoice_from_deal for deal ID 123456789
@zoho-crm-books search_records in accounts for "technology"编程接口
您还可以通过编程方式使用服务器：
import { ZohoMCPServer } from './src/server';
const server = new ZohoMCPServer();
await server.start();错误处理
服务器包括全面的错误处理：
- 身份验证错误：401错误时自动刷新令牌
- 速率限制：对429个错误进行指数级回退
- 验证错误：带有详细错误消息的输入验证
- 网络错误：具有可配置超时的重试逻辑
监控和日志记录
服务器包括内置监控：
- 请求/响应日志记录
- 性能指标
- 误差跟踪
- 健康检查
安全
- OAuth 2.0基于令牌的身份验证
- 安全的令牌存储和刷新
- 输入验证和净化
- 速率限制保护
- HTTPS强制
发展
项目结构
src/
├── auth/ # OAuth authentication
├── clients/ # API clients (CRM, Books)
├── tools/ # MCP tools implementation
├── resources/ # MCP resources implementation
├── types/ # TypeScript type definitions
└── server.ts # Main server implementation测试
使用以下工具运行测试：
npm test代码检查
npm run lint格式化
npm run format贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加测试
- 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
支持
对于问题和疑问：
- 在GitHub上创建问题
- 查看Zoho API文档
- 审查MCP规范
更新日志
v1.0.0
- 初始版本
- CRM和图书集成
- OAuth 2.0身份验证
- 基本同步功能
- MCP服务器实现