使用说明

ZOHO MCP 服务器

一个用于在ZOHO服务中查询和设置元数据的模型上下文协议（MCP）服务器。

特点/特性

连接到各种ZOHO服务（如CRM、Books、Desk等）
从ZOHO服务中查询和检索元数据
在ZOHO服务中设置和配置元数据
通过MCP协议提供ZOHO服务管理工具

安装

快速入门（推荐）

克隆仓库并安装依赖项：

git clone <repository-url>
cd zoho_mcp
uv sync
uv pip install -e .

这将：

安装所有必需的依赖项 pyproject.toml
安装 zoho_mcp_server 在开发模式下打包

使用uv进行手动安装

如果您想手动安装：

uv add "mcp[cli]>=1.1.0" httpx pydantic python-dotenv
uv pip install -e .

使用虚拟环境中的 pip

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

配置

第一步：获取ZOHO API凭证

要使用此服务器，您需要创建一个ZOHO OAuth应用程序：

首选 ZOHO API 控制台
创建一个新的“基于服务器的应用程序”
记下你的 Client ID 并且 Client Secret
生成一个 Refresh Token 使用OAuth流程（参见ZOHO文档）

步骤2：配置环境变量

创建一个 .env 在项目根目录中放置包含您的ZOHO凭据的文件：

ZOHO_CLIENT_ID=your_client_id
ZOHO_CLIENT_SECRET=your_client_secret
ZOHO_REFRESH_TOKEN=your_refresh_token
ZOHO_REGION=com  # or eu, in, au, jp, ca depending on your region

你可以复制 .env.example 作为起点：

cp .env.example .env
# Then edit .env with your actual credentials

用法

开发模式

使用MCP Inspector测试服务器：

uv run mcp dev src/zoho_mcp_server/server.py

Claude 桌面集成

将服务器添加到您的Claude Desktop配置中。编辑您的 claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

把这个加到 mcpServers 部分/章节：

{
  "mcpServers": {
    "ZOHO MCP Server": {
      "command": "/absolute/path/to/zoho_mcp/.venv/bin/python",
      "args": [
        "-m",
        "zoho_mcp_server"
      ]
    }
  }
}

重要的：

替换 /absolute/path/to/zoho_mcp/ 加上你项目目录的实际路径
在Windows上，请使用完整路径 .venv\Scripts\python.exe
更新配置后，请重启 Claude Desktop 以使更改生效

直接执行

直接运行服务器：

uv run zoho-mcp-server

可用工具

list_zoho_services列出可用的ZOHO服务
get_service_modules获取特定ZOHO服务（例如，CRM、Books、Desk）的可用模块
get_module_fields获取ZOHO服务中特定模块的字段元数据
search_records在ZOHO模块中根据可选条件和分页设置搜索记录
create_record在ZOHO模块中创建一条新记录
update_record在ZOHO模块中更新现有记录

可用资源

zoho://services可用的ZOHO服务列表
zoho://service/{service}/modules特定服务中可用的模块
zoho://service/{service}/module/{module}/fields特定模块的字段元数据

可用提示

zoho_query_prompt为ZOHO操作生成有用的提示（搜索、创建、更新）

示例

服务器启动后，您可以通过Claude Desktop或任何MCP客户端使用它：

列出可用的ZOHO服务：

Use the list_zoho_services tool

获取CRM模块：

Use get_service_modules with service="crm"

获取潜在客户模块的字段：

Use get_module_fields with service="crm" and module="Leads"

寻找潜在客户线索：

Use search_records with service="crm", module="Leads", criteria="(Email:equals:test@example.com)"

创建一个新的潜在客户：

Use create_record with service="crm", module="Leads", and record_data containing the lead fields

支持的ZOHO服务

服务器提供对以下ZOHO服务的访问：

CRM（客户关系管理）
书籍（会计类）
客服台（客户支持）
人员（人力资源管理）
库存（库存管理）
订阅（订阅计费）
（电子邮件营销的）活动/宣传活动
调查（在线调查）
项目（项目管理）

发展

项目结构

zoho_mcp/
├── src/
│   └── zoho_mcp_server/
│       ├── __init__.py
│       ├── __main__.py       # Entry point
│       ├── server.py          # MCP server implementation
│       ├── config.py          # Configuration settings
│       └── zoho_client.py     # ZOHO API client
├── .env.example              # Example environment variables
├── pyproject.toml            # Project dependencies
└── README.md

运行测试

uv run pytest

代码质量

uv run ruff check
uv run mypy src/

故障排除

缺失依赖项错误

如果你看到 ModuleNotFoundError: No module named 'mcp'，运行：

uv sync

认证错误

无效或已过期的刷新令牌

如果你看到 Failed to refresh access token - invalid_code您的刷新令牌无效或已过期。

解决方法：

前往ZOHO API控制台 根据您的地区：
- 欧盟地区：https://api-console.zoho.eu/
- 美国：https://api-console.zoho.com/
- 印度：https://api-console.zoho.in/
- 澳大利亚：https://api-console.zoho.com.au/
- 日本：https://api-console.zoho.jp/
- 加拿大：https://api-console.zoho.ca/
导航至您的服务器端应用程序:
- 点击您现有的应用程序或创建一个新的
- 转到“生成代码”选项卡（或“自定义客户端”选项卡）
生成一个新的刷新令牌:
- 选择所需的范围（例如。， ZohoCRM.modules.ALL， ZohoCRM.settings.ALL)
- 设置时间持续（选择适当的过期时间）
- 点击“生成”
- 复制生成的代码

从代码生成刷新令牌：

使用提供的代码生成刷新令牌
您可以使用ZOHO API控制台的内置工具或发送POST请求：

curl -X POST "https://accounts.zoho.eu/oauth/v2/token" \
  -d "code=YOUR_GENERATED_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code"

更新你的 .env 文件：

ZOHO_REFRESH_TOKEN=your_new_refresh_token_here

重启服务器

错误的区域配置

验证您的 .env 文件包含正确的凭据
请确认您正在使用正确的地区（com，eu，in，au，jp，ca）
你所在地区的 .env 必须与您的ZOHO账户注册时所填写的信息一致

缺少凭据

如果你看到关于缺失凭据的错误：

确保 ZOHO_CLIENT_ID， ZOHO_CLIENT_SECRET，以及 ZOHO_REFRESH_TOKEN 都已准备好 .env
检查值周围没有多余的空格或引号

模块导入错误

如果你看到 ModuleNotFoundError: No module named 'zoho_mcp_server'：

确保软件包已安装:
```
uv pip install -e .
```

使用正确的入口点：

# ✅ Correct - using installed module
python -m zoho_mcp_server
# or
.venv/bin/python -m zoho_mcp_server

# ❌ Wrong - running file directly will fail with import errors
python src/zoho_mcp_server/server.py

对于Claude Desktop确保你的配置使用的是虚拟环境中的 Python：

{
  "command": "/absolute/path/to/zoho_mcp/.venv/bin/python",
  "args": ["-m", "zoho_mcp_server"]
}

调试代币问题

在排查令牌问题时，如需查看详细日志，您可以通过设置日志级别来启用调试日志记录：

# In your terminal before running the server
export LOG_LEVEL=DEBUG
uv run zoho-mcp-server

这将显示有关令牌刷新过程的详细信息，包括确切的API请求和响应。

贡献

欢迎贡献！请随时提交拉取请求。

许可证

麻省理工学院许可证