AmoCRM MCP Server

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

Задавайте вопросы на русском — 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: "у меня 19 инструментов — get_leads, get_contacts..."
3. Пользователь пишет вопрос на русском
4. Claude решает какие инструменты вызвать и в каком порядке
5. MCP-сервер передаёт запросы в AmoCRM API v4, возвращает JSON
6. Claude анализирует данные и отвечает пользователю

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

Установка

Вариант A: uvx (рекомендуется для MCP-клиентов)

uvx запускает Python-пакеты в изолированном окружении, поэтому не нужно клонировать репозиторий, создавать .venv или вручную устанавливать зависимости. Окружение и зависимости кэшируются после первого запуска.

Один раз установите uv:

winget install --id astral-sh.uv -e

После публикации пакета в PyPI добавьте в конфигурацию MCP-клиента:

{
  "mcpServers": {
    "amocrm": {
      "command": "uvx",
      "args": ["--from", "catgirl3d-amocrm-mcp==0.3.2", "amocrm-mcp"]
    }
  }
}

Для первичной OAuth2-авторизации выполните один раз:

uvx --from catgirl3d-amocrm-mcp==0.3.2 amocrm-mcp-auth

Токены сохраняются в ~/.amocrm/config.json. Если MCP-клиент не находит uvx, укажите абсолютный путь к нему; в Windows его можно узнать командой where uvx.

Вариант B: pip

pip install catgirl3d-amocrm-mcp

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

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

Публикация в PyPI

Пакет уже настроен через pyproject.toml: он содержит зависимости, метаданные и команды amocrm-mcp / amocrm-mcp-auth. Для публикации новой версии:

# Проверить тесты
uv run --with pytest pytest -q

# Собрать wheel и source distribution в dist/
uv build

# Опубликовать dist/* в PyPI
uv publish

Для uv publish нужен аккаунт PyPI и API token. Перед командой публикации задайте токен через переменную UV_PUBLISH_TOKEN; токен нельзя добавлять в Git или README. Версия из pyproject.toml (0.3.2) должна быть новой: PyPI не позволяет заменить уже загружанный файл той же версии.

После публикации проверьте установку именно из PyPI:

uvx --from catgirl3d-amocrm-mcp==0.3.2 amocrm-mcp

Настройка

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

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

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

Если используется запуск через uvx:

uvx --from catgirl3d-amocrm-mcp==0.3.2 amocrm-mcp-auth

Если пакет установлен через pip, используйте:

amocrm-mcp-auth

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

python3 auth_setup.py

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

• Субдомен — часть URL вашего AmoCRM (например mycompany из mycompany.amocrm.ru)
• Client ID и Client Secret — из шага 1
• Redirect URI — обязателен, точно как в настройках интеграции (например https://localhost)
• Auth code — скрипт сначала попросит Authorization code из карточки интеграции; если кода там нет — откроет страницу авторизации и попросит 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": ["/путь/до/catgirl3d-amocrm-mcp/server.py"]}

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

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

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

5. Проверить

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

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

Инструмент	Что делает
get_pipelines	Воронки продаж с этапами и их ID
get_leads	Сделки с фильтрами (менеджер, воронка, статус(ы), даты, сумма)
count_and_sum_leads	Подсчёт и сумма сделок без лимита 200 — для аналитики
get_leads_grouped_by_company	Сделки по компаниям с суммами (LTV) — топ-N без лимита 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 ₽ в работе
Сколько неразобранных заявок?
Какие кастомные поля есть у сделок?
Причины отказа по проигранным сделкам

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

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

Токены

• Хранятся в ~/.amocrm/config.json
• Обновляются автоматически при истечении access_token
• Если протухли — снова запустите 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
• uv — изолированный запуск Python-пакетов через uvx
• AmoCRM API v4 (OAuth2)
• Без внешних HTTP-библиотек — urllib из stdlib

Лицензия

MIT