金大哥 - zoho-crm-mcp-server MCP 详情

article

README

🚀 Zoho CRM MCP Server

Zoho CRM MCP Server 是一个用于将 Zoho CRM 与 GenAI 应用程序集成的 Model Context Protocol (MCP) 服务器，它提供了标准化接口，让 AI 助手和应用程序能与 CRM 数据进行交互。

🚀 快速开始

本 MCP 服务器可实现与 Zoho CRM 的无缝集成，使 AI 助手和应用程序能够通过标准化接口与您的 CRM 数据进行交互。

✨ 主要特性

🔐 OAuth 2.0 认证：安全认证，支持自动刷新令牌。
📊 全面的 CRM 操作：全面支持潜在客户、联系人、交易等操作。
⚡ 速率限制：内置速率限制，以遵守 API 配额。
🔄 自动重试逻辑：智能重试机制，采用指数退避策略。
🛡️ 错误处理：强大的错误处理和日志记录功能。
🎯 MCP 协议合规：完全符合 Model Context Protocol 规范。
🚀 异步支持：异步操作，提升性能。

📦 安装指南

从 PyPI 安装（发布后）

pip install zoho-crm-mcp-server

从源代码安装

git clone https://github.com/asklokesh/zoho-crm-mcp-server.git
cd zoho-crm-mcp-server
pip install -e .

开发环境安装

pip install -e ".[dev]"

💻 使用示例

作为独立服务器运行

zoho-crm-mcp

在 Python 代码中使用

from zoho_crm_mcp import ZohoCRMMCPServer
import asyncio

async def main():
    server = ZohoCRMMCPServer()
    await server.run()

if __name__ == "__main__":
    asyncio.run(main())

使用 Zoho CRM 客户端

from zoho_crm_mcp import ZohoCRMClient, Config
import asyncio

async def main():
    config = Config()
    client = ZohoCRMClient(config)
    
    await client.initialize()
    
    # 获取潜在客户
    leads = await client.get_leads(page=1, per_page=50)
    print(f"Found {len(leads['data'])} leads")
    
    # 创建新的潜在客户
    new_lead = await client.create_lead({
        "Last_Name": "Doe",
        "First_Name": "John",
        "Email": "john.doe@example.com",
        "Company": "Acme Corp"
    })
    
    # 搜索记录
    results = await client.search_records(
        "Leads",
        "(Email:equals:john.doe@example.com)"
    )
    
    await client.close()

if __name__ == "__main__":
    asyncio.run(main())

📚 详细文档

配置

1. 设置 Zoho OAuth 凭证

访问 Zoho API 控制台。
创建一个新的自客户端应用程序。
记录您的客户端 ID 和客户端密钥。
使用所需范围生成刷新令牌：
- ZohoCRM.modules.ALL
- ZohoCRM.settings.ALL

2. 创建环境配置

复制示例配置文件：

cp .env.example .env

编辑 .env 文件，填入您的凭证：

ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_REFRESH_TOKEN=your_refresh_token_here

# 可选配置
ZOHO_API_DOMAIN=https://www.zohoapis.com
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_PERIOD=60
MAX_RETRIES=3
LOG_LEVEL=INFO

开发

运行测试

pytest tests/ -v --cov=zoho_crm_mcp

代码检查

ruff check src/ tests/
ruff format src/ tests/

构建项目

python -m build

CI/CD

本项目包含 GitHub Actions 工作流，用于：

✅ 在 Python 3.8 - 3.12 版本上进行自动化测试。
🔍 使用 Ruff 进行代码质量检查。
📦 包构建和验证。
📊 代码覆盖率报告。

架构

zoho-crm-mcp-server/
├── src/zoho_crm_mcp/
│   ├── __init__.py       # 包初始化
│   ├── server.py         # MCP 服务器实现
│   ├── zoho_client.py    # Zoho CRM API 客户端
│   └── config.py         # 配置管理
├── tests/                # 全面的测试套件
├── .github/workflows/    # CI/CD 管道
└── pyproject.toml        # 项目配置

错误处理

服务器包含全面的错误处理：

令牌过期：令牌过期时自动刷新。
速率限制：通过智能退避策略遵守 API 速率限制。
网络错误：采用指数退避策略自动重试。
验证错误：为无效配置提供清晰的错误消息。

日志记录

服务器使用 Python 内置的日志模块。通过环境变量配置日志级别：

export LOG_LEVEL=DEBUG  # 选项: DEBUG, INFO, WARNING, ERROR, CRITICAL

贡献

欢迎贡献代码！请随意提交拉取请求。

分叉仓库
创建您的功能分支 (git checkout -b feature/AmazingFeature)
提交您的更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开拉取请求

故障排除

常见问题

问题：ModuleNotFoundError: No module named 'mcp' 解决方案：安装 MCP SDK：pip install mcp

问题：令牌刷新失败 解决方案：验证您的刷新令牌是否有效，并具有所需的范围。

问题：速率限制错误 解决方案：在 .env 文件中调整 RATE_LIMIT_REQUESTS 和 RATE_LIMIT_PERIOD。

要求

Python 3.8+
requests >= 2.25.0
mcp >= 1.0.0
python-dotenv >= 0.19.0

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

如有问题、疑问或想要贡献代码，请访问：

致谢

Model Context Protocol - MCP 规范
Zoho CRM API - API 文档
所有帮助改进本项目的贡献者

为 MCP 社区用心打造 ❤️

zoho-crm-mcp-server