amocrm-mcp

🗄 リポジトリはアーカイブされました

開発は theYahia/WWmcp に移行しました。CIS、MENA、アフリカ、LATAM、東南アジアなど、西側諸国以外の API 向け MCP サーバーのモノレポです。共通コア @theyahia/mcp-core、統合 CI、統合リリースパイプラインを備えています。

ここにあったものの現行バージョンはこちらです：servers/amocrm/

npm パッケージは従来どおり @theyahia/amocrm-mcp です。これまでどおりインストールして使えます。 このリポジトリは今後更新されません。課題やプルリクエストは WWmcp にお願いします。

アーカイブ済み — 開発は theYahia/WWmcp に移行しました。 西側諸国以外の API 向け MCP サーバーのモノレポです。 このパッケージの現行バージョンは servers/amocrm/ にあります。 npm パッケージ @theyahia/amocrm-mcp に変更はありません。 課題やプルリクエストは、そちらにお寄せください。

amoCRM MCP — AI で取引、連絡先、営業パイプラインを管理

amoCRM を AI アシスタントに接続する方法を探している方、自然な言葉でパイプラインの状況を確認したり、取引を登録したり、画面を開かずに連絡先を検索したりしたい方におすすめです。amoCRM 向けの 19 個のツールで、取引、連絡先、企業、パイプライン、タスク、メモ、検索、イベント、未処理項目を扱えます。OAuth 2.0 によるトークンの自動更新、毎秒 7 件のリクエスト制限、指数バックオフによる再試行に対応しています。

インストール

npx -y @theyahia/amocrm-mcp

MCP の設定

Claude Desktop、Cursor、その他の MCP クライアントの設定に追加してください：

{
  "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.amocrm.ru の mycompany）
AMOCRM_ACCESS_TOKEN	はい	OAuth アクセストークン
AMOCRM_REFRESH_TOKEN	いいえ	OAuth リフレッシュトークン（401 時の自動更新を有効にします）
AMOCRM_CLIENT_ID	いいえ	OAuth クライアント ID（トークンの更新に必要です）
AMOCRM_CLIENT_SECRET	いいえ	OAuth クライアントシークレット（トークンの更新に必要です）

AMOCRM_DOMAIN も AMOCRM_SUBDOMAIN の別名として受け付けます（後方互換性のため）。

ツール（19 個）

取引

ツール	説明
list_leads	フィルター（パイプライン、ステータス、検索クエリ）を使って取引を検索・一覧表示します。連絡先と失注理由も取得します。
get_lead	ID を指定して、関連する連絡先とカタログ項目を含む取引を 1 件取得します。
create_lead	名前、予算、パイプライン、ステータス、カスタムフィールドを指定して取引を作成します。
update_lead	取引のフィールドを更新します。ステージ間の移動、予算の変更、担当者の変更ができます。

連絡先

ツール	説明
list_contacts	名前、電話番号、メールアドレスで連絡先を検索します。
get_contact	すべてのカスタムフィールドを含む連絡先を 1 件取得します。
create_contact	電話番号、メールアドレス、カスタムフィールドを指定して連絡先を作成します。

企業

ツール	説明
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. Обменяйте код на токены:

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

Разработка

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

Лицензия

MIT

---

Telegram: @vhodvai