Zoho CRM MCP Server (FastAPI + FastMCP)

Production-grade сервер Model Context Protocol (MCP), построенный на FastAPI + FastMCP, который предоставляет Claude и другим AI-клиентам полный аутентифицированный доступ к Zoho CRM REST API v8 — от чтения записей до проектирования модулей и создания автоматизации рабочих процессов.

167 MCP-инструментов, покрывающих записи, COQL, проектирование схемы, правила рабочих процессов и их действия, вебхуки, массовые операции, теги, заметки, электронную почту, настройки безопасности, а также массовый импорт/экспорт — плюс универсальный инструмент zoho_api_request для всего, что Zoho предоставляет, но для чего нет отдельного инструмента.

🌟 Ключевые возможности

• Веб-фреймворк FastAPI: Высокопроизводительное production-ready ASGI-приложение на базе Uvicorn.

• Двойной транспорт: Работает как Streamable HTTP MCP-сервер (для удалённого/облачного хостинга) и как STDIO MCP-сервер (для локального Claude Desktop).

• Полный жизненный цикл OAuth 2.0: Автоматический обмен кода, обработчик перенаправления в браузере (/auth/callback), зашифрованное хранение токенов и фоновый цикл, поддерживающий токен актуальным, пока сервер работает.

• Учётные данные, настраиваемые из чата: Указывайте Zoho Client ID/Secret прямо из чата (set_zoho_credentials, или инлайн в get_auth_url/exchange_auth_code) вместо .env — удобно для переключения между Zoho-аккаунтами без перезапуска.

• Полное создание автоматизации: Создавайте правила рабочих процессов от начала до конца — создавайте действия обновления полей, email-уведомлений, задач и вебхуков, затем подключайте их к правилу с триггерами и критериями.

• Проектирование схемы: Создавайте пользовательские модули (с профилями, которые требует Zoho), поля, глобальные пиклисты, макеты и воронки продаж.

• Режим ограниченной сессии: Фильтр безопасности на основе ID (activate_scope), ограничивающий операции конкретными ID записей.

• Утверждения с участием человека (HITL): Деструктивные действия ставятся в очередь ожидающих запросов вместо выполнения. Переключается с помощью ZOHO_REQUIRE_APPROVAL.

• Структурированное журналирование активности: Каждое событие аутентификации, вызов API и решение об утверждении записывается в формате JSON и доступно через get_logs() / GET /logs.

• Зашифрованное хранение токенов: OAuth-токены шифруются при хранении (Fernet/AES), никогда не хранятся в открытом виде.

• Устойчивый сетевой клиент: Пул httpx-клиентов с автоматическим обновлением токена при 401 и повтором, ограничением частоты при 429, экспоненциальным повтором при 5xx, ограничителем исходящей скорости и обнаружением частичных сбоев в по-записных ответах Zoho.

• Автоматизированный набор тестов: 35 тестов pytest, покрывающих HTTP-поверхность, регистрацию инструментов, формы полезной нагрузки запросов и защитные механизмы клиента.

Related MCP server: Zoho CRM MCP Server

📁 Структура репозитория

zoho-crm-mcp/
├── server.py              # FastAPI app + all FastMCP tool definitions & REST endpoints
├── auth_manager.py        # OAuth 2.0 flow, scopes & token refresh
├── zoho_client.py         # Async HTTP client for Zoho CRM API v8 (151 methods)
├── models.py              # Pydantic state & validation models
├── token_store.py         # Encrypted (Fernet) token persistence
├── approval_manager.py    # HITL approval queue for high-risk actions
├── activity_log.py        # Structured JSON activity logger
├── test_server.py         # pytest suite
├── requirements.txt       # Dependencies
├── .env.example           # Environment configuration template
├── pyproject.toml         # Package metadata
└── README.md

⚙️ Установка и настройка

1. Предварительные требования

• Python 3.10+

• Приложение Zoho CRM API Console (Zoho API Console)

  • Тип клиента: Server-based Applications

  • Redirect URI: http://localhost:8000/auth/callback (или URL обратного вызова вашего развёртывания)

2. Настройка окружения

cp .env.example .env

Минимальная конфигурация:

ZOHO_CLIENT_ID=1000.xxxxxxx
ZOHO_CLIENT_SECRET=xxxxxxx
ZOHO_REDIRECT_URI=http://localhost:8000/auth/callback
ZOHO_DATA_CENTER=com
PORT=8000

Все поддерживаемые переменные, включая шлюз утверждений, переопределение OAuth-скоупа, ограничение частоты и настройки таймаутов, см. в .env.example.

Работаете более чем с одним Zoho-аккаунтом? ZOHO_CLIENT_ID/ZOHO_CLIENT_SECRET необязательны. Оставьте их пустыми и попросите Claude вызвать set_zoho_credentials(client_id, client_secret, redirect_uri?, data_center?), или передайте client_id/client_secret напрямую в get_auth_url / exchange_auth_code. Переключение client_id очищает токены, сохранённые для предыдущего аккаунта, что предотвращает ошибку Zoho invalid_client при повторном использовании refresh-токена, выданного другому приложению.

3. Установка зависимостей

pip install -r requirements.txt

🚀 Запуск и развёртывание

Вариант A: Локальный веб-сервер FastAPI

python server.py

Или напрямую через Uvicorn:

uvicorn server:app --host 0.0.0.0 --port 8000

После запуска:

• Веб-панель: http://localhost:8000/

• Swagger Docs: http://localhost:8000/docs

• Проверка здоровья: http://localhost:8000/health

• MCP Endpoint: http://localhost:8000/mcp

Вариант B: Локальный STDIO

python server.py --stdio

Вариант C: Облачное развёртывание (Render, Railway, Docker, AWS, Heroku)

• Команда запуска: uvicorn server:app --host 0.0.0.0 --port $PORT

• Путь проверки здоровья: /health

• Переменные окружения: задайте ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET, ZOHO_REDIRECT_URI, ZOHO_DATA_CENTER и ZOHO_TOKEN_ENCRYPTION_KEY (чтобы токены переживали перезапуски на эфемерных файловых системах).

🖥️ Интеграция с Claude Desktop

Режим 1: HTTP / удалённое MCP-подключение

{
  "mcpServers": {
    "zoho-crm": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Режим 2: Локальное STDIO-подключение

{
  "mcpServers": {
    "zoho-crm": {
      "command": "python",
      "args": ["C:/Users/Lenovo/Desktop/zoho MCP/server.py", "--stdio"],
      "env": {
        "ZOHO_CLIENT_ID": "1000.YOUR_CLIENT_ID",
        "ZOHO_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "ZOHO_REDIRECT_URI": "http://localhost:8000/auth/callback",
        "ZOHO_DATA_CENTER": "com"
      }
    }
  }
}

🔑 OAuth-поток при первом запуске

1. Запустите сервер: python server.py

2. Откройте http://localhost:8000/auth/url или попросите Claude выполнить get_auth_url().

3. Откройте полученный URL, войдите в Zoho CRM, нажмите Accept.

4. Zoho перенаправит на /auth/callback?code=...; сервер обменяет код и сохранит зашифрованные токены в ~/.zoho_crm_tokens.json.

🧩 Создание автоматизации: рецепт рабочего процесса

Zoho моделирует правило рабочего процесса как триггер плюс условия, где каждое условие указывает на заранее созданные объекты действий. Создавайте их в таком порядке:

1. get_workflow_configurations(module="Leads")
   -> see which triggers, comparators, and action types this org supports

2. create_field_update_action(
       name="Mark as Hot", module="Leads",
       field_api_name="Rating", value="Hot")
   -> returns the action id

3. create_workflow(
       name="Hot Lead Router",
       module="Leads",
       execute_when={"type": "create_or_edit"},
       conditions=[{
           "sequence_number": 1,
           "criteria_details": {"criteria": {"group_operator": "and", "group": [
               {"comparator": "equal",
                "field": {"api_name": "Lead_Source"},
                "value": "Web Form"}]}},
           "instant_actions": {"actions": [
               {"id": "<action id from step 2>", "type": "field_updates"}]}}])

4. activate_workflow(workflow_id="...")

Тот же принцип применяется с create_email_notification_action, create_automation_task и create_webhook в качестве источника действий.

🎯 Режим ограниченной сессии (фильтр безопасности)

Ограничьте каждую операцию конкретными ID записей:

• Активация: activate_scope(module="Deals", record_ids=["4153...001", "4153...002"])

• REST: POST /scope/activate с {"module": "Leads", "record_ids": ["123", "456"]}

• Деактивация: deactivate_scope() или POST /scope/deactivate

Пока режим активен, чтение в этом модуле фильтруется по этим ID, а запись в любой другой ID отклоняется с ошибкой OUT_OF_SCOPE.

✅ Утверждения с участием человека (HITL)

По умолчанию деструктивные действия ставятся в очередь ожидающих запросов и возвращают request_id вместо выполнения:

delete_record, bulk_update_records, bulk_delete_records, mass_update_records, mass_delete_records, change_owner, mass_change_owner, merge_records, delete_workflow, delete_workflows, execute_blueprint, update_layout, activate_layout, delete_layout, delete_field, delete_user, delete_tag, bulk_write_create_job.

• Просмотр: list_pending_approvals() или GET /approvals

• Утвердить и выполнить: approve_action(request_id="...") или POST /approvals/{id}/approve

• Отклонить и отбросить: reject_action(request_id="...") или POST /approvals/{id}/reject

• Полностью отключить шлюз: задайте ZOHO_REQUIRE_APPROVAL=false, чтобы эти инструменты выполнялись немедленно.

Каждый запрос, утверждение и отклонение записывается в журнал активности.

📜 Журналирование активности

События аутентификации, исходящие вызовы Zoho API, выполнение функций и решения об утверждениях записываются как записи {timestamp, action, status, details} — хранятся в памяти и дописываются в ~/.zoho_crm_mcp_activity.log.jsonl.

• Получение: get_logs(limit=50, action=None, status=None) или GET /logs

🔐 Безопасность токенов

• Токены шифруются при хранении (Fernet/AES) в ~/.zoho_crm_tokens.json.

• Ключ автоматически генерируется в ~/.zoho_crm_mcp.key при первом запуске (с правами только для пользователя на POSIX) или задаётся явно через ZOHO_TOKEN_ENCRYPTION_KEY для стабильного ключа при перезапусках контейнера.

• Токены помечаются client_id, который их выдал, и отбрасываются при несовпадении, что предотвращает ошибку Zoho invalid_client после переключения аккаунтов.

• Исходящие вызовы самоограничиваются (ZOHO_RATE_LIMIT_PER_SEC, по умолчанию 10/сек) в дополнение к откату при 429/5xx.

🧪 Тестирование

pytest -v

Покрывает HTTP-поверхность (/health, /, /auth/*, /scope/*, /approvals/*, /logs), регистрацию всех 167 MCP-инструментов, точные формы полезной нагрузки для рабочих процессов/модулей/заметок/звонков/вебхуков/объединений/блокировок, защитные механизмы валидации на стороне клиента, ограничение частоты и обнаружение частичных сбоев Zoho.

Тесты полностью работают офлайн — учётные данные Zoho не требуются.

🛠️ Справочник MCP-инструментов

† По умолчанию требуют одобрения. Установите ZOHO_REQUIRE_APPROVAL=false для немедленного выполнения.

* В публичном REST API Zoho CRM нет эндпоинта для этой операции — создание блюпринтов, исходный код функций Deluge и создание отчетов/панелей мониторинга доступны только через интерфейс или относятся к отдельному продукту Zoho Analytics. Эти инструменты возвращают понятное сообщение NOT_SUPPORTED_BY_ZOHO_API с указанием рабочей альтернативы, а не завершаются ошибкой при обращении к несуществующему URL.

🧭 Доступ ко всему, что не перечислено

API Zoho больше, чем любая написанная вручную обёртка. zoho_api_request покрывает остальное с той же аутентификацией, ограничением частоты запросов и обработкой повторных попыток:

zoho_api_request(
    method="GET",
    endpoint="settings/territories")

zoho_api_request(
    method="POST",
    endpoint="settings/automation/scoring_rules",
    body={"scoring_rules": [{...}]})

zoho_api_request(
    method="GET",
    endpoint="read/1234567890",
    api_root="bulk")