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安装(推荐)```bash
Install using uvx (recommended for CLI tools)
uvx zoho-crm-mcp
Or install using pip
pip install zoho-crm-mcp
### 选项2:从源代码安装
1. **克隆此存储库**:```bash
git clone
cd zoho-crm-mcp
- 安装依赖项:```bash
uv sync
or
pip install -e .
## 设置
### 第一步:创建Zoho开发者应用
1. 首选 Zoho开发者控制台
1. 创建新的“基于服务器的应用程序”应用程序
1. 记下你的 `Client ID` 和 `Client Secret`
1. 将重定向URI设置为 `http://localhost:8080/callback`
### 步骤2:配置环境变量
创建一个 `.env` 工作目录中的文件:```bash
# Copy the example file
cp .env.example .env
编辑 .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服务器之前,您需要手动生成身份验证令牌:
### 第一步:生成代币
运行身份验证帮助程序以生成令牌:```bash
# 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` 文件:```bash
# Authentication Tokens
ZOHO_ACCESS_TOKEN=your_generated_access_token_here
ZOHO_REFRESH_TOKEN=your_generated_refresh_token_here
⚠️ 重要:确保这些令牌的安全,永远不要将其提交给版本控制!
运行MCP服务器
配置好令牌后,您可以运行服务器:```bash
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````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"
}
}
}
}
**如果本地安装,则采用替代配置:**```json
{
"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兼容客户端,请将其配置为运行:```bash
Using uvx (recommended)
uvx --from zoho-crm-mcp zoho-mcp
Or if installed locally via pip
zoho-mcp
## 错误处理
服务器提供全面的错误处理:
- **身份验证错误**:清除有关缺少或无效凭据的消息
- **API错误**:来自Zoho CRM API的详细错误消息
- **网络错误**:连接和超时错误处理
- **数据验证**:输入参数验证
所有错误都以一致的格式返回:```json
{
"error": "Description of the error",
"details": "Additional error details if available"
}
安全考虑
当前实施(开发)
- 刷新令牌存储在
.env文件(纯文本) - 适用于开发和测试
生产建议
- 将刷新令牌存储在加密数据库中
- 使用安全密钥管理服务(AWS KMS、Azure密钥库等)
- 实施代币轮换政策
- 使用环境变量进行敏感配置
- 启用审核日志记录
- 实施速率限制
扩展服务器
要添加新工具,请执行以下操作:
- 将该功能添加到
zoho_mcp/zoho_tools.py:```python
def new_tool_function(param1: str, param2: int) -> Dict[str, Any]:
Implementation
pass
1. **在中创建MCP工具包装器 `zoho_mcp/server.py`**:```python
@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请求:python
import logging
logging.basicConfig(level=logging.DEBUG)
API费率限制
Zoho CRM有API利率限制:
- 免费版:每天200个API调用
- 付费版本:根据计划提高限额
服务器没有实现速率限制,因此请相应地监控您的使用情况。
支持
关于以下问题:
- Zoho CRM API:检查 Zoho CRM API文档
- MCP协议:检查 模型上下文协议规范
- 此服务器:检查错误消息和日志
许可证
本项目按原样提供,用于教育和发展目的。
