amocrm-mcp 0.3.0

MCP server for AmoCRM — gives Claude Desktop direct access to your CRM

AmoCRM MCP Server

MCP-сервер для AmoCRM. Подключается к Claude Desktop и даёт Claude прямой доступ к вашей CRM через 17 инструментов.

Задавайте вопросы на русском — Claude сам вызовет нужные API и скомбинирует ответ.

Архитектура

┌──────────────────┐     stdin/stdout      ┌──────────────────┐     HTTPS      ┌──────────────┐
│  Claude Desktop  │ ◄──── MCP Protocol ──► │  amocrm-mcp      │ ◄── REST ───► │  AmoCRM API  │
│  (LLM + UI)      │                        │  (локальный)      │                │  (облако)    │
└──────────────────┘                        └──────────────────┘                └──────────────┘

Как это работает:

1. Claude Desktop запускает amocrm-mcp как subprocess
2. MCP-сервер сообщает Claude: "у меня 17 инструментов — get_leads, get_contacts..."
3. Пользователь пишет вопрос на русском
4. Claude решает какие инструменты вызвать и в каком порядке
5. MCP-сервер передаёт запросы в AmoCRM API v4, возвращает JSON
6. Claude анализирует данные и отвечает пользователю

Внутри MCP-сервера нет ИИ — это прокси между Claude и AmoCRM.

Установка

Вариант A: pip (рекомендуется)

pip install amocrm-mcp

Вариант B: из исходников

git clone https://github.com/ilyaberdysh/amocrm-mcp.git
cd amocrm-mcp
pip install -e .

Настройка

1. Создать интеграцию в AmoCRM

1. AmoCRM → Настройки → Интеграции → Создать интеграцию
2. Тип: Внешняя интеграция
3. Redirect URI: https://localhost
4. Скопировать Client ID и Client Secret

2. Авторизоваться

amocrm-mcp-auth

Или если установлено из исходников:

python3 auth_setup.py

Скрипт спросит:

• Субдомен — часть URL вашего AmoCRM (например mycompany из mycompany.amocrm.ru)
• Client ID и Client Secret — из шага 1
• Redirect URI — по умолчанию https://localhost
• Auth code — откроется URL, авторизуетесь, скопируете code из URL редиректа

Токены сохранятся в ~/.amocrm/config.json.

3. Подключить к Claude Desktop

Откройте файл конфигурации:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Добавьте:

{
  "mcpServers": {
    "amocrm": {
      "command": "amocrm-mcp"
    }
  }
}

Если установлено из исходников, укажите полный путь:

{"command": "python3", "args": ["/путь/до/amocrm-mcp/server.py"]}

4. Перезапустить Claude Desktop

Cmd+Q (Mac) / Alt+F4 (Windows) → открыть заново.

В чате появится иконка инструментов — amocrm с 17 тулами.

5. Проверить

Покажи мои воронки в AmoCRM

Инструменты (17)

Инструмент	Что делает
get_pipelines	Воронки продаж с этапами и их ID
get_leads	Сделки с фильтрами (менеджер, воронка, статус, даты, сумма)
count_and_sum_leads	Подсчёт и сумма сделок без лимита 200 — для аналитики
get_contacts	Контакты (поиск по имени, email, телефону)
get_companies	Компании
get_users	Пользователи / менеджеры
get_tasks	Задачи (активные/выполненные, сортировка по дедлайну)
get_notes	Примечания к сделкам, контактам, компаниям
get_events	Журнал событий (смена этапов, создание сделок)
get_customers	Покупатели (повторные клиенты)
get_unsorted	Неразобранные заявки
get_catalogs	Каталоги товаров/услуг
get_catalog_elements	Элементы каталогов
get_custom_fields	Пользовательские поля сущностей
get_loss_reasons	Причины отказа
get_tags	Теги
get_sources	Источники трафика

Примеры запросов

Сколько сделок закрыто в феврале 2025?
Сравни продажи за этот и прошлый месяц
Кто из менеджеров закрыл больше всего сделок?
Покажи просроченные задачи Никиты
Сделки на этапе "Переговоры" во всех воронках
Найди сделки дороже 500 000 ₽ в работе
Сколько неразобранных заявок?
Какие кастомные поля есть у сделок?
Причины отказа по проигранным сделкам

Структура проекта

amocrm-mcp/
├── server.py           # MCP-сервер — точка входа, 17 tool definitions
├── amocrm_client.py    # AmoCRM API v4 клиент
│                         - OAuth2 с auto-refresh токенов
│                         - Retry на 429 (rate limit) с backoff 2s/5s/10s
│                         - Пагинация до 10 000 записей
│                         - Обработка пустых ответов API
├── config.py           # Чтение/запись ~/.amocrm/config.json
├── auth_setup.py       # CLI для первичной OAuth2 авторизации
├── pyproject.toml      # Метаданные, зависимости, entry points
└── QA_TEST_PROMPT.md   # QA-промпт для тестирования (10 вопросов)

Токены

• Хранятся в ~/.amocrm/config.json
• Обновляются автоматически при каждом запросе
• Протухают если не использовать > 3 месяцев
• Если протухли — снова запустите amocrm-mcp-auth

Отладка

# Проверить что сервер запускается
amocrm-mcp
# Если висит без ошибок — ждёт подключения (Ctrl+C для выхода)

# Проверить конфиг
cat ~/.amocrm/config.json

# Логи Claude Desktop
# Mac: ~/Library/Logs/Claude/
# Windows: %APPDATA%\Claude\logs\

Требования

• Python 3.11+
• Claude Desktop
• Аккаунт AmoCRM с правами создания интеграций

Технологии

• MCP SDK — Model Context Protocol
• AmoCRM API v4 (OAuth2)
• Без внешних HTTP-библиотек — urllib из stdlib

Лицензия

MIT