Zoho CRM MCP服务器
一个模型上下文协议（MCP）服务器，提供与Zoho CRM的无缝集成。该服务器将Zoho CRM功能作为MCP工具公开，可供Claude、GPT和其他MCP兼容客户端等AI助手使用。
特性
- 完全OAuth2身份验证：使用OAuth2流通过Zoho CRM进行安全身份验证
- 环境变量：使用.env文件进行安全凭据管理
- 联系人管理：搜索、创建和更新联系人
- 交易管理：搜索、创建和列出交易
- 用户信息：获取当前用户详细信息
- STDIO传输：使用标准输入/输出与MCP客户端兼容
- 错误处理：全面的错误处理，错误信息清晰
- 许可证管理：自动访问令牌刷新
- PyPI就绪：可通过pip/uvx安装，便于分发
先决条件
- Python 3.11或更高版本
- 具有API访问权限的Zoho CRM帐户
- Zoho开发者控制台应用程序凭据
安装
选项1：从PyPI安装（推荐）
# Install using uvx (recommended for CLI tools)
uvx zoho-crm-mcp
# Or install using pip
pip install zoho-crm-mcp选项2：从源代码安装
- 克隆此存储库:
git clone
cd zoho-crm-mcp- 安装依赖项:
uv sync
# or
pip install -e .设置
第一步：创建Zoho开发者应用
- 首选 Zoho开发者控制台
- 创建新的“基于服务器的应用程序”应用程序
- 记下你的
Client ID和Client Secret - 将重定向URI设置为
http://localhost:8080/callback
步骤2：配置环境变量
创建一个 .env 工作目录中的文件：
# Copy the example file
cp .env.example .env编辑 .env 使用您的凭据：
ZOHO_CLIENT_ID=your_actual_client_id
ZOHO_CLIENT_SECRET=your_actual_client_secret
ZOHO_REDIRECT_URI=http://localhost:8080/callback
ZOHO_API_DOMAIN=https://www.zohoapis.com
ZOHO_SCOPE=ZohoCRM.modules.ALL,ZohoCRM.users.READ身份验证设置
在运行MCP服务器之前，您需要手动生成身份验证令牌：
第一步：生成代币
运行身份验证帮助程序以生成令牌：
# Using uvx (recommended)
uvx --from zoho-crm-mcp zoho-mcp-auth
# Or if installed locally via pip
zoho-mcp-auth
# Or using uv from source
uv run zoho-mcp-auth这将指导您完成OAuth流程：
🔐 Zoho CRM Manual Token Generation
===================================
Step 1: Visit the authorization URL
====================================
Please visit this URL to authorize the application:
https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.ALL%2CZohoCRM.users.ALL%2CZohoCRM.org.ALL&client_id=your_client_id&response_type=code&redirect_uri=https%3A%2F%2Flocalhost&access_type=offline
Step 2: Get the authorization code
==================================
After authorization, you'll be redirected to your redirect_uri.
Copy the 'code' parameter from the redirect URL and paste it below.
Enter authorization code: [paste your code here]
✅ Token generation successful!
Step 3: Add tokens to your .env file
====================================
Add the following lines to your .env file:
ZOHO_ACCESS_TOKEN=your_generated_access_token
ZOHO_REFRESH_TOKEN=your_generated_refresh_token步骤2：将令牌添加到.env文件
复制生成的令牌并将其添加到您的 .env 文件：
# Authentication Tokens
ZOHO_ACCESS_TOKEN=your_generated_access_token_here
ZOHO_REFRESH_TOKEN=your_generated_refresh_token_here⚠️ 重要：确保这些令牌的安全，永远不要将其提交给版本控制！
运行MCP服务器
配置好令牌后，您可以运行服务器：
# Using uvx (recommended)
uvx --from zoho-crm-mcp zoho-mcp
# Or if installed locally via pip
zoho-mcp
# Or using uv from source
uv run zoho-mcp服务器将验证您的身份验证并启动：
Fetching user information...
✓ Authenticated as: Your Name (your.email@example.com)
Zoho CRM MCP Server running on stdio可用的MCP工具
1. get_contact_by_email_tool
通过电子邮件地址搜索联系人。
参数：
email（string）：要搜索的电子邮件地址
退货：
- 联系信息，包括ID、姓名、电话、帐户和时间戳
2. create_contact_tool
在Zoho CRM中创建新联系人。
参数：
first_name（string）：联系人的名字last_name（string）：联系人的姓氏email（string）：联系人的电子邮件地址phone（string）：联系人的电话号码
退货：
- 已创建联系人ID和状态
3. get_deal_by_name_tool
按名称搜索交易。
参数：
deal_name（string）：要搜索的交易名称
退货：
- 交易信息，包括ID、金额、阶段、联系人和日期
4. create_deal_tool
在Zoho CRM中创建新交易。
参数：
deal_name（string）：交易名称contact_id（string）：关联联系人的IDstage（字符串）：交易阶段（例如，“资格认证”、“提案”、“谈判”、“最终获胜”）amount（浮动）：交易金额
退货：
- 已创建交易ID和状态
5. update_contact_tool
更新现有联系人的特定字段。
参数：
contact_id（string）：要更新的联系人的IDfield（string）：要更新的字段名（例如，“电话”、“电子邮件”、“First_name”）value（string）：字段的新值
退货：
- 更新状态和确认
6. list_open_deals_tool
列出所有未结交易（不包括已结交易）。
参数： 无
退货：
- 一系列包含细节的公开交易
7. get_user_info_tool
获取当前经过身份验证的用户信息。
参数： 无
退货：
- 用户信息，包括姓名、电子邮件、角色和个人资料
与MCP客户端一起使用
克劳德桌面
将此服务器添加到您的Claude Desktop配置中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"zoho-crm": {
"command": "uvx",
"args": ["--from", "zoho-crm-mcp", "zoho-mcp"],
"env": {
"ZOHO_CLIENT_ID": "your_zoho_client_id",
"ZOHO_CLIENT_SECRET": "your_zoho_client_secret",
"ZOHO_REDIRECT_URI": "http://localhost:8080/callback",
"ZOHO_API_DOMAIN": "https://www.zohoapis.com",
"ZOHO_SCOPE": "ZohoCRM.modules.ALL,ZohoCRM.users.ALL,ZohoCRM.org.ALL",
"ZOHO_ACCESS_TOKEN": "your_generated_access_token",
"ZOHO_REFRESH_TOKEN": "your_generated_refresh_token"
}
}
}
}如果本地安装，则采用替代配置：
{
"mcpServers": {
"zoho-crm": {
"command": "zoho-mcp",
"args": [],
"env": {
"ZOHO_CLIENT_ID": "your_zoho_client_id",
"ZOHO_CLIENT_SECRET": "your_zoho_client_secret",
"ZOHO_REDIRECT_URI": "http://localhost:8080/callback",
"ZOHO_API_DOMAIN": "https://www.zohoapis.com",
"ZOHO_SCOPE": "ZohoCRM.modules.ALL,ZohoCRM.users.ALL,ZohoCRM.org.ALL",
"ZOHO_ACCESS_TOKEN": "your_generated_access_token",
"ZOHO_REFRESH_TOKEN": "your_generated_refresh_token"
}
}
}
}其他MCP客户端
对于其他MCP兼容客户端，请将其配置为运行：
# Using uvx (recommended)
uvx --from zoho-crm-mcp zoho-mcp
# Or if installed locally via pip
zoho-mcp错误处理
服务器提供全面的错误处理：
- 身份验证错误：清除有关缺少或无效凭据的消息
- API错误：来自Zoho CRM API的详细错误消息
- 网络错误：连接和超时错误处理
- 数据验证：输入参数验证
所有错误都以一致的格式返回：
{
"error": "Description of the error",
"details": "Additional error details if available"
}安全考虑
当前实施（开发）
- 刷新令牌存储在
.env文件（纯文本） - 适用于开发和测试
生产建议
- 将刷新令牌存储在加密数据库中
- 使用安全密钥管理服务（AWS KMS、Azure密钥库等）
- 实施代币轮换政策
- 使用环境变量进行敏感配置
- 启用审核日志记录
- 实施速率限制
扩展服务器
要添加新工具，请执行以下操作：
- 将该功能添加到
zoho_mcp/zoho_tools.py:
def new_tool_function(param1: str, param2: int) -> Dict[str, Any]:
# Implementation
pass- 在中创建MCP工具包装器
zoho_mcp/server.py:
@mcp.tool()
def new_tool(param1: str, param2: int) -> Dict[str, Any]:
"""
Description of the new tool.
Args:
param1: Description of parameter 1
param2: Description of parameter 2
Returns:
Description of return value
"""
return new_tool_function(param1, param2)- 更新文档
故障排除
常见问题
- “缺少.env文件”错误:
- 创建一个 .env 工作目录中的文件 - 复制自 .env.example 并填写您的凭据
- “未通过身份验证”错误:
- 跑 zoho-mcp-auth 设置身份验证 - 检查你的 .env 文件具有有效凭据
- “令牌刷新失败”:
- 重新运行OAuth设置过程 - 从中删除旧令牌 .env 并重新验证
- “API请求失败”:
- 验证您的Zoho CRM权限 - 检查API域是否适用于您所在的地区
- “未找到联系人/交易”:
- 验证搜索条件 - 检查该记录是否存在于您的CRM中
环境变量问题
- 缺少环境变量:
- 确保 ZOHO_CLIENT_ID 和 ZOHO_CLIENT_SECRET 已设置 .env - 检查 .env.example 查看完整列表
- 无效凭证:
- 验证您的 ZOHO_CLIENT_ID 和 ZOHO_CLIENT_SECRET - 确保它们与您的Zoho Developer Console应用程序匹配
- 重定向URI错误:
- 确保 ZOHO_REDIRECT_URI 匹配您的Zoho应用程序配置 - 默认值应为 http://localhost:8080/callback
- 身份验证流程问题:
- 如果身份验证失败，请删除 ZOHO_ACCESS_TOKEN 和 ZOHO_REFRESH_TOKEN 从 .env - 重新启动服务器以触发新的OAuth流
调试模式
对于调试，您可以添加日志以查看API请求：
import logging
logging.basicConfig(level=logging.DEBUG)API费率限制
Zoho CRM有API利率限制：
- 免费版：每天200个API调用
- 付费版本：根据计划提高限额
服务器没有实现速率限制，因此请相应地监控您的使用情况。
支持
关于以下问题：
- Zoho CRM API：检查 Zoho CRM API文档
- MCP协议：检查 模型上下文协议规范
- 此服务器：检查错误消息和日志
许可证
本项目按原样提供，用于教育和发展目的。