使用说明

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 <repository-url>
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）：关联联系人的ID
stage （字符串）：交易阶段（例如，“资格认证”、“提案”、“谈判”、“最终获胜”）
amount （浮动）：交易金额

退货：

已创建交易ID和状态

5. `update_contact_tool`

更新现有联系人的特定字段。

参数：

contact_id （string）：要更新的联系人的ID
field （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协议：检查模型上下文协议规范
此服务器：检查错误消息和日志

许可证

本项目按原样提供，用于教育和发展目的。

使用说明

Zoho CRM MCP服务器

特性

先决条件

安装

选项1：从PyPI安装（推荐）

选项2：从源代码安装

设置

第一步：创建Zoho开发者应用

步骤2：配置环境变量

身份验证设置

第一步：生成代币

步骤2：将令牌添加到.env文件

运行MCP服务器

可用的MCP工具

1. get_contact_by_email_tool

2. create_contact_tool

3. get_deal_by_name_tool

4. create_deal_tool

5. update_contact_tool

6. list_open_deals_tool

7. get_user_info_tool

与MCP客户端一起使用

克劳德桌面

其他MCP客户端

错误处理

安全考虑

当前实施（开发）

生产建议

扩展服务器

故障排除

常见问题

环境变量问题

调试模式

API费率限制

支持

许可证

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

AI开发助手

必应中文搜索MCP服务器

PostgreSQL管理服务器

网页内容获取工具

1. `get_contact_by_email_tool`

2. `create_contact_tool`

3. `get_deal_by_name_tool`

4. `create_deal_tool`

5. `update_contact_tool`

6. `list_open_deals_tool`

7. `get_user_info_tool`