Zoho Crm

Zoho CRM MCP サーバー

Zoho CRM を GenAI アプリケーションと連携するための Model Context Protocol（MCP）サーバーです。

概要

この MCP サーバーは Zoho CRM とシームレスに連携し、AI アシスタントやアプリケーションが標準化されたインターフェースを通じて CRM データを操作できるようにします。

特長

• 🔐 OAuth 2.0 認証 - トークンを自動更新するセキュアな認証
• 📊 包括的な CRM 操作 - リード、連絡先、商談などを幅広くサポート
• ⚡ レート制限 - API のクォータを遵守するためのレート制限機能を内蔵
• 🔄 自動リトライロジック - 指数バックオフを用いたインテリジェントなリトライ機構
• 🛡️ エラー処理 - 堅牢なエラー処理とログ記録
• 🎯 MCP プロトコル準拠 - Model Context Protocol 仕様に完全準拠
• 🚀 非同期処理のサポート - パフォーマンスを向上させる非同期操作

利用可能なツール

サーバーは以下の 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 Console にアクセスします
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

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

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 コミュニティに ❤️ を込めて