How do I use amocrm-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@amocrm-mcp Сколько сделок на этапе переговоры?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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)      │                        │  (локальный)      │                │  (облако)    │
└──────────────────┘                        └──────────────────┘                └──────────────┘

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

Claude Desktop запускает amocrm-mcp как subprocess
MCP-сервер сообщает Claude: "у меня 17 инструментов — get_leads, get_contacts..."
Пользователь пишет вопрос на русском
Claude решает какие инструменты вызвать и в каком порядке
MCP-сервер передаёт запросы в AmoCRM API v4, возвращает JSON
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

AmoCRM → Настройки → Интеграции → Создать интеграцию
Тип: Внешняя интеграция
Redirect URI: https://localhost
Скопировать 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

amocrm-mcp