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. 新しいSelf Clientアプリケーションを作成します。
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 Issues
• GitHub Discussions

謝辞

• Model Context Protocol - MCP仕様
• Zoho CRM API - APIドキュメント
• このプロジェクトを改善するために貢献してくれたすべての方々

MCPコミュニティのために❤️で作られました。