MCP Zoho Crm

MCP办公协作

提供方 Rezasz

办公协作 stdio · 本地进程 OAuth 授权 社区 / 第三方
查看接入方式

Zoho CRM V8的模型上下文协议(MCP)服务器,提供全面的API集成功能,包括CRUD操作、元数据管理、文件上传、批量操作和COQL查询等。适用于企业客户关系管理系统的开发和集成。

一句话选型结论

按资料字段整理

MCP Zoho Crm 属于办公协作类 MCP 服务器,stdio · 本地进程,OAuth 授权,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类办公协作 传输方式stdio · 本地进程 鉴权OAuth 授权 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 19 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

办公协作
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量19暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

适用场景

CRM集成Python本地部署API服务器数据管理企业软件自动化工具

安装与配置

stdio · 本地进程 OAuth 授权
客户端在本机拉起子进程,数据不出本机
pip install -e .

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 19 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
日程与消息

查日程、发消息、约会议。

表单与审批

填表单、走审批流。

团队协作

同步任务、汇总进展。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 19 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在办公协作场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
MCP Zoho Crm当前 19 stdio · 本地进程 本地部署 有 2026-05-17
CowAgent 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Karakeep MCP 未标注 未标注 未标注 无 2026-05-17
agentscope 未标注 stdio · 本地进程 本地部署 有 2026-04-11
note-gen 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Everywhere 未标注 stdio · 本地进程 本地部署 有 2026-04-12

服务器档案

办公协作
字段来自项目仓库与公开索引,中文说明由本站标注
提供方Rezasz上游标注的维护方 Rezasz
分类办公协作本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

15.1 KB
来自项目仓库与上游目录的原文,未做删改

Zoho CRM V8 MCP服务器

用于Zoho CRM V8 API集成的综合模型上下文协议(MCP)服务器。此服务器提供对所有Zoho CRM API的无缝访问,包括CRUD操作、元数据管理、文件上传、批量操作、COQL查询等。

特性

✨ API全面覆盖

  • CRUD操作:获取、搜索、创建、更新、删除记录
  • 元数据API:模块、字段、布局、自定义视图、相关列表
  • 文件API:将文件上传到Zoho文件系统(每个文件最多20MB)
  • COQL:执行类似SQL的查询以进行复杂的数据检索
  • 批量操作:用于大型数据集的异步批量读/写
  • 复合API:在单个请求中组合多达5个API调用
  • 通知:启用/禁用实时通知

🔐 强健的身份验证

  • OAuth 2.0,带有自动令牌刷新功能
  • 安全令牌管理
  • 指数退避自动重试

⚡ 性能优化

  • HTTP请求的连接池
  • 元数据缓存(可配置TTL)
  • 自动分页处理
  • 费率限制管理

🛡️ 全面的错误处理

  • 所有Zoho API错误的详细错误映射
  • 带有解决提示的用户友好错误消息
  • 临时故障自动重试

✅ 完全验证

  • 参数约束执行
  • 模块特定验证
  • 字段限制检查
  • 分页规则验证

安装

先决条件

  • Python 3.10或更高版本
  • 具有API访问权限的Zoho CRM帐户
  • OAuth 2.0凭据(客户端ID、客户端密码、刷新令牌)

设置

  1. 克隆存储库:```bash
    git clone https://github.com/yourusername/MCP-Zoho-CRM.git
    cd MCP-Zoho-CRM

2. 安装依赖项:```bash
pip install -e .
  1. 配置环境变量:```bash
    cp .env.example .env

Edit .env with your Zoho OAuth credentials


### OAuth 2.0设置

#### 第一步:注册您的申请

1. 首选 Zoho API控制台
1. 创建新的 **自助客户端** 应用
1. 注意你的 **客户端ID** 和 **客户端密钥**

#### 步骤2:生成刷新令牌

1. 生成授权码URL:```
https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoCRM.bulk.ALL,ZohoCRM.coql.READ,ZohoSearch.securesearch.READ,ZohoCRM.Files.CREATE&client_id=YOUR_CLIENT_ID&response_type=code&access_type=offline&redirect_uri=YOUR_REDIRECT_URI
  1. 访问浏览器中的URL并授权应用程序

  2. 从重定向URL复制授权码

  3. 将代码替换为刷新令牌:```bash
    curl -X POST "https://accounts.zoho.com/oauth/v2/token" \
    -d "grant_type=authorization_code" \
    -d "client_id=YOUR_CLIENT_ID" \
    -d "client_secret=YOUR_CLIENT_SECRET" \
    -d "code=YOUR_AUTH_CODE" \
    -d "redirect_uri=YOUR_REDIRECT_URI"


5. 保存 **refresh_token** 从回复中

#### 步骤3:配置环境

编辑 `.env` 文件:```env
ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_REFRESH_TOKEN=your_refresh_token_here

# API Domain (change based on your data center)
ZOHO_API_DOMAIN=https://www.zohoapis.com  # US
# ZOHO_API_DOMAIN=https://www.zohoapis.eu  # EU
# ZOHO_API_DOMAIN=https://www.zohoapis.in  # India
# ZOHO_API_DOMAIN=https://www.zohoapis.com.au  # Australia
# ZOHO_API_DOMAIN=https://www.zohoapis.jp  # Japan

需要OAuth作用域

完整功能需要以下范围:

  • ZohoCRM.modules.ALL -完全访问所有模块
  • ZohoCRM.settings.ALL -访问元数据和设置
  • ZohoCRM.bulk.ALL -批量读/写操作
  • ZohoCRM.coql.READ -COQL查询执行
  • ZohoSearch.securesearch.READ -高级搜索功能
  • ZohoCRM.Files.CREATE -文件上传功能
  • ZohoCRM.Files.READ -文件读取功能

对于特定于模块的访问,请使用:

  • ZohoCRM.modules.{module}.READ
  • ZohoCRM.modules.{module}.CREATE
  • ZohoCRM.modules.{module}.UPDATE
  • ZohoCRM.modules.{module}.DELETE

用法

运行服务器```bash

python -m mcp_zoho_crm.server


或与MCP客户端一起使用:```json
{
"mcpServers": {
"zoho-crm": {
"command": "python",
"args": ["-m", "mcp_zoho_crm.server"],
"env": {
"ZOHO_CLIENT_ID": "your_client_id",
"ZOHO_CLIENT_SECRET": "your_client_secret",
"ZOHO_REFRESH_TOKEN": "your_refresh_token"
}
}
}
}

可用工具

记录CRUD操作

1. zoho_get_records

从具有高级过滤和分页功能的模块中获取记录。

参数:

  • module (必需):模块API名称(例如,“潜在客户”、“联系人”、“交易”)
  • record_id:要获取的特定记录ID
  • fields:字段API名称的列表(最大50个,大容量提取必须使用)
  • per_page:每页记录数(默认200条,最多200条)
  • page:页码(仅1-10页,最多2000条记录)
  • page_token:标记超过2000条记录的分页
  • sort_by:排序字段(“id”、“Created_Time”、“Modified_Time”)
  • sort_order:排序顺序(“sc”或“desc”)
  • cvid:自定义视图ID
  • territory_id:区域ID(仅限交易、联系人、帐户)

例子:```json
{
"module": "Leads",
"fields": ["First_Name", "Last_Name", "Email", "Company"],
"per_page": 50,
"page": 1,
"sort_by": "Created_Time",
"sort_order": "desc"
}


#### 2. `zoho_search_records`

使用条件、电子邮件、电话或单词搜索搜索记录。

**参数:**

- `module` (必需):模块API名称
- `criteria`:搜索条件(最多10个条件)
- `email`:要搜索的电子邮件地址
- `phone`:要搜索的电话号码
- `word`:要搜索的单词(最少2个字符)

**例子:**```json
{
"module": "Leads",
"criteria": "((Company:equals:Acme) and (City:equals:New York))"
}

3. zoho_create_records

在模块中创建新记录。

参数:

  • module (必需):模块API名称
  • records (必填):记录数据列表(最多100个)
  • trigger:自动触发执行
  • lar_id:分配规则ID

例子:```json
{
"module": "Leads",
"records": [
{
"Last_Name": "Doe",
"First_Name": "John",
"Email": "john.doe@example.com",
"Company": "Acme Corp"
}
]
}


#### 4. `zoho_update_records`

更新现有记录。

**参数:**

- `module` (必需):模块API名称
- `records` (必填):带“id”字段的记录数据列表(最多100个)
- `record_id`:特定记录ID(用于单记录更新)

**例子:**```json
{
"module": "Leads",
"records": [
{
"id": "5843104000000624046",
"Email": "newemail@example.com",
"Phone": "+1-555-0123"
}
]
}

5. zoho_delete_records

从模块中删除记录。

参数:

  • module (必需):模块API名称
  • record_ids (必填):记录ID列表(最多100个)

例子:```json
{
"module": "Leads",
"record_ids": ["5843104000000624046", "5843104000000624047"]
}


### 元数据API

#### 6. `zoho_get_modules`

获取所有模块或特定模块的元数据。

**例子:**```json
{
"module": "Leads",
"use_cache": true
}

7. zoho_get_fields

获取字段元数据,包括数据类型、约束和最大长度。

例子:```json
{
"module": "Contacts",
"use_cache": true
}


#### 8. `zoho_get_layouts`

获取布局元数据,包括字段排列和管道。

**例子:**```json
{
"module": "Deals",
"use_cache": true
}

9. zoho_get_custom_views

获取自定义视图配置。

例子:```json
{
"module": "Leads",
"use_cache": true
}


#### 10. `zoho_get_related_lists`

获取模块的可用相关列表。

**例子:**```json
{
"module": "Accounts"
}

文件API

11. zoho_upload_files

将文件上传到Zoho文件系统。

参数:

  • files (必填):文件路径列表(最多10个,每个20MB)
  • file_type:可选类型(内联图像为“内联”)

例子:```json
{
"files": ["/path/to/document.pdf", "/path/to/image.jpg"],
"file_type": "inline"
}


### API公司

#### 12. `zoho_execute_coql`

执行类似SQL的COQL查询。

**例子:**```json
{
"query": "SELECT First_Name, Last_Name, Email FROM Leads WHERE City = 'New York' AND Rating = 'Hot'"
}

批量API

13. zoho_bulk_read

为大型数据集创建批量读取作业。

例子:```json
{
"module": "Contacts",
"fields": ["First_Name", "Last_Name", "Email", "Phone"],
"criteria": "((Created_Time:greater_than:2024-01-01T00:00:00+00:00))",
"file_type": "csv"
}


#### 14. `zoho_get_bulk_read_job`

获取批量读取作业状态和下载URL。

**例子:**```json
{
"job_id": "5843104000001856001"
}

15. zoho_bulk_write

为批处理操作创建批量写入作业。

例子:```json
{
"module": "Leads",
"file_id": "5843104000001234567",
"operation": "insert"
}


#### 16. `zoho_get_bulk_write_job`

获取批量写入作业状态。

**例子:**```json
{
"job_id": "5843104000001856002"
}

复合API

17. zoho_composite_request

在单个请求中执行最多5个API调用。

例子:```json
{
"requests": [
{
"method": "GET",
"url": "/crm/v8/Leads?fields=Last_Name,Email&per_page=2"
},
{
"method": "POST",
"url": "/crm/v8/Contacts",
"body": {
"data": [
{
"Last_Name": "Smith",
"Email": "smith@example.com"
}
]
}
}
]
}


### 通知API

#### 18. `zoho_enable_notifications`

启用实时通知。

**例子:**```json
{
"channel_id": "my_channel_1",
"events": ["Leads.create", "Leads.edit"],
"notify_url": "https://myapp.com/webhook"
}

19. zoho_disable_notifications

禁用通知。

例子:```json
{
"channel_ids": ["my_channel_1", "my_channel_2"]
}


## 常见工作流

### 工作流程1:创建新潜在客户```python
# Step 1: Get field metadata to understand required fields
get_fields_result = zoho_get_fields(module="Leads")

# Step 2: Create the lead
create_result = zoho_create_records(
module="Leads",
records=[
{
"Last_Name": "Johnson",
"First_Name": "Sarah",
"Email": "sarah.johnson@techcorp.com",
"Company": "TechCorp Inc",
"Phone": "+1-555-0199",
"Lead_Status": "Contacted"
}
]
)

工作流程2:搜索和更新交易```python

Step 1: Search for deals in specific stage

search_result = zoho_search_records(
module="Deals",
criteria="((Stage:equals:Negotiation) and (Amount:greater_than:50000))"
)

Step 2: Update found deals

update_result = zoho_update_records(
module="Deals",
records=[
{
"id": deal["id"],
"Stage": "Closed Won",
"Closing_Date": "2024-12-31"
}
for deal in search_result["data"]
]
)


### 工作流程3:批量导出联系人```python
# Step 1: Create bulk read job
bulk_job = zoho_bulk_read(
module="Contacts",
fields=["First_Name", "Last_Name", "Email", "Phone", "Account_Name"],
file_type="csv"
)

# Step 2: Check job status (poll until completed)
job_status = zoho_get_bulk_read_job(job_id=bulk_job["data"][0]["id"])

# Step 3: Download the file using the download_url from job_status

API约束和限制

分页限制

  • 记录1-2000:使用 page 和 per_page 参数
  • 记录2001-100000:必须使用 page_token 从响应
  • 最大每页:200条记录(标准),2000条(批量读取)
  • 最大分页:共100000条记录

字段限制

  • 请求中的最大字段数:50个字段
  • 最大搜索条件:10个条件

记录限制

  • 每次创建/更新的最大记录数:100条记录
  • 每次删除的最大记录数:100条记录
  • 最大搜索结果数:2000条记录

文件限制

  • 最大文件大小:每个文件20 MB
  • 每次上传的最大文件数:10个文件

复合API

  • 最大请求数:每个复合请求5个API调用

错误处理

服务器通过用户友好的消息提供全面的错误处理:

常见错误

OAUTH_SCOPE_MISMATCH(401)

问题:缺少所需的OAuth作用域
解决方案:使用所需的作用域重新生成令牌

离散分页限制已超过(400)

问题:请求超过2000条没有page_token的记录
解决方案:使用 page_token 2000年以后的记录回复

模糊处理(400)

问题:使用不兼容的参数(例如,page+page_token)
解决方案:使用其中之一 page 或 page_token,不是两者都有

已超过限制(400)

问题:超出请求限制
解决方案:减少请求中的字段/记录/标准数量

重复数据(400)

问题:唯一字段中的重复值
解决方案:使用其他值或更新现有记录

模块特定规则

引导模块

  • 必填字段: Last_Name
  • 支持 converted 参数('false'、'true'、'both')
  • 转换字段: Converted__s, Converted_Date_Time

联系人模块

  • 必填字段: Last_Name
  • 支持区域过滤
  • 只读: full_name (名字+姓氏的串联)

账户模块

  • 必填字段: Account_Name
  • 支持区域过滤

交易模块

  • 必填字段: Deal_Name, Stage
  • 启用管道时: Pipeline 也是必需的
  • 支持区域过滤
  • 使用GetPipelinesneneneba API获取管道详细信息

任务模块

  • 必填字段: Subject (多线)

呼叫模块

  • 必填字段: Subject, Call_Type, Call_Start_Time, Call_Duration
  • 约束: Call_Duration 不能为零

事件模块

  • 必填字段: Event_Title, Start_DateTime, End_DateTime, Remind_At
  • 最多参与者:50

产品模块

  • 必填字段: Product_Name

报价单/发票/销售订单/采购订单

  • 必修的: Subject 和行项目子表单
  • 库存子表单仅在获取特定记录时可用

发展

项目结构```

MCP-Zoho-CRM/
├── src/
│ └── mcp_zoho_crm/
│ ├── init.py
│ ├── auth.py # OAuth 2.0 authentication
│ ├── client.py # Base API client
│ ├── cache.py # Metadata caching
│ ├── config.py # Configuration management
│ ├── errors.py # Error handling
│ ├── records.py # CRUD operations
│ ├── metadata.py # Metadata APIs
│ ├── files.py # Files API
│ ├── coql.py # COQL queries
│ ├── bulk.py # Bulk operations
│ ├── composite.py # Composite API
│ ├── notifications.py # Notifications
│ └── server.py # MCP server
├── pyproject.toml
├── README.md
├── .env.example
└── .gitignore


### 测试```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests (when available)
pytest

故障排除

令牌刷新问题

  • 在中验证OAuth凭据 .env
  • 检查刷新令牌是否未过期
  • 确保包括所需的范围
  • 验证API域是否与您的数据中心匹配

速率限制

  • 服务器以指数回退方式自动重试
  • 最大重试次数:4次尝试(可配置)
  • 等待时间:2秒、4秒、8秒、16秒

分页错误

  • 对于>2000条记录,请始终使用 page_token
  • 使用时不要修改参数 page_token
  • page_token 24小时后过期

文件上传失败

  • 检查文件大小(最大20MB)
  • 验证是否支持文件格式
  • 确保文件存在且可读
  • 检查文件中的病毒/恶意软件

支持和资源

  • Zoho CRM API文档
  • OAuth 2.0安装指南
  • API控制台
  • Zoho开发者社区

许可证

MIT许可证-有关详细信息,请参阅许可证文件

贡献

欢迎投稿!请随时提交拉取请求。

更新日志

版本1.0.0(2024-11-15)

  • 初始版本
  • 完整的Zoho CRM V8 API支持
  • OAuth 2.0身份验证,自动刷新
  • 全面的错误处理
  • 元数据缓存
  • 所有CRUD操作
  • 批量API
  • COQL支持
  • 复合API
  • 文件API
  • 通知API

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
MCP Zoho Crm 怎么安装?

在客户端按下面的安装命令接入:pip install -e .。装完在客户端配置里引用同一个包或端点。

MCP Zoho Crm 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

MCP Zoho Crm 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

MCP Zoho Crm 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

MCP Zoho Crm 能提供哪些能力?

资料显示约 19 个工具;能力标签包括 CRM集成、Python、数据管理、API集成。具体工具清单以官方文档为准。

MCP Zoho Crm 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

MCP Zoho Crm 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。