Zoho Crm MCP Server

🚀 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 憑證

1. 訪問 Zoho API 控制檯。
2. 創建一個新的自客戶端應用程序。
3. 記錄您的客戶端 ID 和客戶端密鑰。
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

# 可選配置
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

貢獻

歡迎貢獻代碼！請隨意提交拉取請求。

1. 分叉倉庫
2. 創建您的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打開拉取請求

故障排除

常見問題

問題：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 問題
• GitHub 討論

致謝

• Model Context Protocol - MCP 規範
• Zoho CRM API - API 文檔
• 所有幫助改進本項目的貢獻者

為 MCP 社區用心打造 ❤️