# amocrm-mcp-prm

Форк [`@theyahia/amocrm-mcp`](https://github.com/theYahia/amocrm-mcp) 2.0.2 (MIT). Все 19 исходных инструментов работают как раньше, добавлено 12 новых, фильтры и чтение переписки из мессенджер-шлюза «Чацкий».

## Что добавлено

| Инструмент | Зачем |
|---|---|
| `list_notes` | Читать примечания: комментарии менеджеров, звонки с длительностью и ссылкой на запись, SMS |
| `get_lead_full` | Карточка сделки одним вызовом: поля, этап, ответственный, компания, контакты, примечания, звонки с контакта, задачи, история этапов |
| `leads_summary` | Сводка по сделкам без выгрузки: всего, выиграно, проиграно, разбивка по воронке, этапу, менеджеру, причине отказа, месяцу, тегу, полю |
| `status_transitions` | Переходы между этапами за период: сколько сделок вошло в этап, откуда куда, кто двигал |
| `list_users` | Менеджеры с id и именами |
| `list_loss_reasons` | Причины отказа |
| `list_custom_fields` | Поля сделок, контактов, компаний с id и вариантами |
| `update_contact`, `get_company`, `update_company` | Правка контактов и компаний |
| `link_entities`, `unlink_entities` | Привязать или отвязать контакты и компанию у сделки |

Переписка из Чацкого (включается, если задан `CHATSKY_API_KEY`):

| Инструмент | Зачем |
|---|---|
| `get_lead_dialog` | Переписка по сделке в Telegram и MAX: кто, когда, что написал, расшифровки голосовых, вложения. Только чтение |
| `list_messenger_accounts` | Номера компании в Чацком и их состояние |

С ключом `get_lead_full` сам добавляет переписку в карточку сделки. Отправки сообщений в сервере нет намеренно.

Изменения в старых инструментах:

- `create_lead`: можно сразу привязать существующие контакт и компанию (`contact_id`, `company_id`) или создать новые в том же вызове (`contact`, `company`), а также задать теги. В этих случаях используется `/leads/complex`: один контакт и одна компания на сделку.
- `list_leads`: фильтры `created_from/to`, `updated_from/to`, `closed_from/to`, `responsible_user_ids`, `ids`, сортировка `order_by` и `order_dir`, режим `compact` (читаемые даты, поля в виде «название → значение», без cookies и трекинга).
- `list_events`: `types`, `created_from/to`, `created_by`, `status_after`, `status_before`.
- `list_tasks`: `due_from/to`, `order_dir`, `compact`.

Даты принимаются как `YYYY-MM-DD`, ISO или Unix. Дата без времени читается в поясе аккаунта: переменная `AMOCRM_TZ_OFFSET`, по умолчанию `+03:00`.

## Запуск

Собранный файл без зависимостей: `bundle/amocrm-mcp-prm.mjs`, нужен Node 18+.

```json
{
  "mcpServers": {
    "amocrm": {
      "command": "node",
      "args": ["C:/путь/до/amocrm-mcp-prm.mjs"],
      "env": {
        "AMOCRM_SUBDOMAIN": "<поддомен>",
        "AMOCRM_ACCESS_TOKEN": "<токен>",
        "CHATSKY_API_KEY": "gw_...",
        "CHATSKY_URL": "https://msghub.prmonline.ru"
      }
    }
  }
}
```

Переменные amoCRM те же, что у исходного сервера. `CHATSKY_API_KEY` создается в Чацком: «Настройки» → «Ключи API интеграций». `CHATSKY_URL` можно не указывать, по умолчанию `https://msghub.prmonline.ru`.

Сборка из исходников: `npm install && npm test && npm run bundle`.

Ниже README исходного проекта.

---

# amoCRM MCP — сделки, контакты и воронка продаж через нейросеть

Если вы искали, как подключить amoCRM к ИИ-ассистенту, спросить состояние воронки обычными словами, завести сделку или найти контакт не открывая интерфейс — это оно. 19 инструментов для [amoCRM](https://www.amocrm.ru/): сделки, контакты, компании, воронки, задачи, примечания, поиск, события и неразобранное. OAuth 2.0 с автообновлением токена, ограничение 7 запросов/сек и повтор с экспоненциальной задержкой.

## Установка

```bash
npx -y @theyahia/amocrm-mcp
```

## Настройка MCP

Добавьте в конфигурацию Claude Desktop, Cursor или любого другого MCP-клиента:

```json
{
  "mcpServers": {
    "amocrm": {
      "command": "npx",
      "args": ["-y", "@theyahia/amocrm-mcp"],
      "env": {
        "AMOCRM_SUBDOMAIN": "mycompany",
        "AMOCRM_ACCESS_TOKEN": "your-access-token",
        "AMOCRM_REFRESH_TOKEN": "your-refresh-token",
        "AMOCRM_CLIENT_ID": "your-client-id",
        "AMOCRM_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

## Переменные окружения

| Переменная | Обяз. | Описание |
|----------|----------|-------------|
| `AMOCRM_SUBDOMAIN` | да | Поддомен вашего amoCRM (например, `mycompany` из `mycompany.amocrm.ru`) |
| `AMOCRM_ACCESS_TOKEN` | да | OAuth access-токен |
| `AMOCRM_REFRESH_TOKEN` | нет | OAuth refresh-токен (включает автообновление при 401) |
| `AMOCRM_CLIENT_ID` | нет | OAuth client ID (нужен для обновления токена) |
| `AMOCRM_CLIENT_SECRET` | нет | OAuth client secret (нужен для обновления токена) |

> `AMOCRM_DOMAIN` тоже принимается как алиас `AMOCRM_SUBDOMAIN` (обратная совместимость).

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

### Сделки
| Инструмент | Описание |
|------|-------------|
| `list_leads` | Поиск и список сделок с фильтрами (воронка, статусы, запрос). Подтягивает контакты и причины отказа. |
| `get_lead` | Одна сделка по ID вместе со связанными контактами и элементами каталога. |
| `create_lead` | Создать сделку с названием, бюджетом, воронкой, статусом и пользовательскими полями. |
| `update_lead` | Обновить поля сделки — перевести между этапами, изменить бюджет, сменить ответственного. |

### Контакты
| Инструмент | Описание |
|------|-------------|
| `list_contacts` | Поиск контактов по имени, телефону, e-mail. |
| `get_contact` | Один контакт со всеми пользовательскими полями. |
| `create_contact` | Создать контакт с телефоном, e-mail и пользовательскими полями. |

### Компании
| Инструмент | Описание |
|------|-------------|
| `list_companies` | Поиск компаний. Подтягивает связанные сделки и контакты. |
| `create_company` | Создать компанию с пользовательскими полями. |

### Воронки
| Инструмент | Описание |
|------|-------------|
| `list_pipelines` | Все воронки продаж вместе с их статусами (этапами). |

### Задачи
| Инструмент | Описание |
|------|-------------|
| `list_tasks` | Список задач с фильтрами по сущности, выполненности и ответственному. |
| `create_task` | Создать задачу, привязанную к сделке, контакту или компании, с дедлайном. |
| `complete_task` | Отметить задачу выполненной и добавить текст результата. |

### Неразобранное
| Инструмент | Описание |
|------|-------------|
| `list_unsorted` | Входящие неразобранные заявки (формы, разбор почты). |
| `accept_unsorted` | Принять неразобранную заявку в воронку. |

### Примечания
| Инструмент | Описание |
|------|-------------|
| `add_note` | Добавить примечание (common, call_in, call_out, service_message) к любой сущности. |

### Поиск
| Инструмент | Описание |
|------|-------------|
| `search` | Универсальный поиск по сделкам, контактам и компаниям. |

### События
| Инструмент | Описание |
|------|-------------|
| `list_events` | Лента событий — смены статусов, звонки, примечания, связи. |

### Аккаунт
| Инструмент | Описание |
|------|-------------|
| `get_account` | Информация об аккаунте, пользователи, типы задач, настройки amojo. |

## Демо-промпты

**Обзор продаж:**
> «Покажи все сделки в воронке „Продажи“, которые сейчас на этапе „Переговоры“. С контактами.»

**Работа с задачами:**
> «Создай задачу-перезвон по сделке #12345, дедлайн завтра в 10:00. Потом выведи все мои невыполненные задачи.»

**Заведение нового клиента:**
> «Создай контакт „Иван Петров“ с телефоном +79001234567, потом компанию „Петров Солюшнс“ и сделку „Разработка сайта“ на 150 000 рублей в основной воронке.»

## Как настроить OAuth 2.0

1. Откройте настройки аккаунта amoCRM: `https://YOUR_SUBDOMAIN.amocrm.ru/settings/widgets/`
2. Создайте новую интеграцию (внешняя интеграция)
3. Укажите redirect URI: `https://YOUR_SUBDOMAIN.amocrm.ru`
4. Скопируйте **Client ID** и **Client Secret**
5. Авторизуйте интеграцию, чтобы получить первичный **код авторизации**
6. Обменяйте код на токены:

```bash
curl -X POST https://YOUR_SUBDOMAIN.amocrm.ru/oauth2/access_token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "authorization_code",
    "code": "YOUR_AUTH_CODE",
    "redirect_uri": "https://YOUR_SUBDOMAIN.amocrm.ru"
  }'
```

7. Сохраните `access_token` и `refresh_token` из ответа
8. Сервер сам обновит просроченный токен, если заданы `AMOCRM_REFRESH_TOKEN`, `AMOCRM_CLIENT_ID` и `AMOCRM_CLIENT_SECRET`

## Обработка ошибок

- **401 Unauthorized** — автообновление токена, если настроены реквизиты для refresh, затем повтор запроса
- **429 Rate Limited** — учитывает заголовок `Retry-After`, ждёт и повторяет
- **5xx** — повтор с экспоненциальной задержкой (до 3 попыток)
- **Ограничение частоты** — встроенная пауза 150 мс между запросами (~7 запросов/сек), чтобы укладываться в лимиты amoCRM

## Разработка

```bash
git clone https://github.com/theYahia/amocrm-mcp.git
cd amocrm-mcp
npm install
npm run build
npm test
```

## Лицензия

MIT

---

Telegram: [@vhodvai](https://t.me/vhodvai)