Zoho Crm

Zoho CRM MCP 服务

一个用于将 Zoho CRM 与 GenAI 应用集成的模型上下文协议（MCP）服务。

概览

此 MCP 服务可与 Zoho CRM 无缝集成，让 AI 助手和应用能够通过标准化接口与您的 CRM 数据交互。

功能

• 🔐 OAuth 2.0 身份验证 - 安全身份验证，并自动刷新令牌
• 📊 全面的 CRM 操作 - 全面支持潜在客户、联系人、交易等
• ⚡ 速率限制 - 内置速率限制，以遵守 API 配额
• 🔄 自动重试逻辑 - 采用指数退避的智能重试机制
• 🛡️ 错误处理 - 稳健的错误处理和日志记录
• 🎯 符合 MCP 协议 - 完全符合模型上下文协议规范
• 🚀 异步支持 - 提供异步操作，以提升性能

可用工具

服务提供以下 MCP 工具：

1. get_leads - 从 Zoho CRM 分页获取潜在客户
2. create_lead - 在 Zoho CRM 中创建潜在客户
3. get_contacts - 获取联系人，支持分页
4. get_deals - 从 Zoho CRM 获取交易
5. search_records - 根据自定义条件搜索任意模块

安装

从 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]"

配置

1. 设置 Zoho OAuth 凭据

1. 前往 Zoho API 控制台
2. 创建新的 Self Client 应用
3. 记下您的 Client ID 和 Client Secret
4. 使用所需范围生成刷新令牌：
   • 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

# Optional configurations
ZOHO_API_DOMAIN=https://www.zohoapis.com
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_PERIOD=60
MAX_RETRIES=3
LOG_LEVEL=INFO

使用方法

作为独立服务运行

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()
    
    # Get leads
    leads = await client.get_leads(page=1, per_page=50)
    print(f"Found {len(leads['data'])} leads")
    
    # Create a new lead
    new_lead = await client.create_lead({
        "Last_Name": "Doe",
        "First_Name": "John",
        "Email": "[email protected]",
        "Company": "Acme Corp"
    })
    
    # Search for records
    results = await client.search_records(
        "Leads",
        "(Email:equals:[email protected])"
    )
    
    await client.close()

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

开发

运行测试

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       # Package initialization
│   ├── server.py         # MCP server implementation
│   ├── zoho_client.py    # Zoho CRM API client
│   └── config.py         # Configuration management
├── tests/                # Comprehensive test suite
├── .github/workflows/    # CI/CD pipelines
└── pyproject.toml        # Project configuration

错误处理

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

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

日志记录

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

export LOG_LEVEL=DEBUG  # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL

参与贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 创建 Pull Request

故障排除

常见问题

问题：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 文件

支持

如有问题、疑问或希望参与贡献，请访问：

• GitHub Issues
• GitHub Discussions

致谢

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

---

为 MCP 社区倾情打造 ❤️