AmoCRM MCP Server

Минимальный MCP-сервер для интеграции с amoCRM (API v4): сделки, контакты, заметки, OAuth2.

Требования

• Node.js >= 18.17
• Аккаунт amoCRM и данные интеграции (client_id, client_secret, redirect_uri)

Установка

npm install

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

Создайте файл .env в корне проекта и задайте значения:

AmoCRM настройки

• AMO_BASE_URL — базовый URL аккаунта, например https://example.amocrm.ru
• AMO_CLIENT_ID — client_id интеграции
• AMO_CLIENT_SECRET — client_secret интеграции
• AMO_REDIRECT_URI — redirect URI, если используете Authorization Code Flow
• AMO_ACCESS_TOKEN — access token (после первичного обмена)
• AMO_REFRESH_TOKEN — refresh token (после первичного обмена)
• AMO_LONG_TERM_TOKEN — долгосрочный токен amoCRM (до 5 лет, рекомендуется)

💡 Совет: Используйте долгосрочные токены для упрощения интеграции!

🔐 Безопасность HTTP эндпоинтов (опционально)

• MCP_AUTH_TOKEN — Bearer токен для защиты HTTP/Streamable эндпоинтов

⚠️ Важно: Если вы используете HTTP или Streamable HTTP транспорты, настоятельно рекомендуется установить MCP_AUTH_TOKEN для защиты ваших данных от несанкционированного доступа!

Пример генерации безопасного токена:

# Linux/macOS
openssl rand -hex 32

# Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Подробнее: SECURITY.md

Запуск

STDIO транспорт (для Claude Desktop)

# Разработка
npm run dev

# Продакшн
npm run build
npm run start

HTTP транспорт (для внешнего доступа)

# Разработка
npm run dev:http

# Продакшн
npm run build
npm run start:http

Пример использования с токеном:

# Установка токена
export MCP_AUTH_TOKEN="your-secret-token-here"

# Запуск сервера
npm run start:http

# Тестирование
curl -H "Authorization: Bearer your-secret-token-here" \
     http://localhost:8080/tools

Streamable HTTP транспорт (для MCP клиентов с SSE)

# Разработка
npm run dev:streamable

# Продакшн
npm run build
npm run start:streamable

Пример использования с токеном:

# SSE подключение
curl -H "Accept: text/event-stream" \
     -H "Authorization: Bearer your-secret-token-here" \
     http://localhost:8080/mcp

Подключение MCP-клиента

Claude Desktop (macOS)

1. Откройте ~/Library/Application Support/Claude/claude_desktop_config.json
2. Добавьте секцию:

{
  "mcpServers": {
    "amocrm": {
      "command": "node",
      "args": ["/Users/agrabarnick/Desktop/WORK/dev/amo/mcp/dist/index.js"],
      "env": {
        "AMO_BASE_URL": "https://example.amocrm.ru",
        "AMO_CLIENT_ID": "<client_id>",
        "AMO_CLIENT_SECRET": "<client_secret>",
        "AMO_REDIRECT_URI": "https://your.app/oauth/callback",
        "AMO_ACCESS_TOKEN": "",
        "AMO_REFRESH_TOKEN": ""
      }
    }
  }
}

Примечание: для разработки можно указать запуск через npm run dev, если клиент позволяет задать команду/аргументы.

OAuth2 (получение токенов)

1. Получите authorization code согласно документации amoCRM (через браузерный flow вашей интеграции).
2. В клиенте MCP вызовите инструмент amocrm.exchangeAuthCode с параметрами:

{
  "code": "<authorization_code>",
  "redirect_uri": "https://your.app/oauth/callback"
}

3. В ответе придут access_token, refresh_token, expires_in. Сохраните их в .env.
4. Далее сервер автоматически обновляет access_token по refresh_token.

Доступные инструменты

• amocrm.listLeads({ page?: number, limit?: number })
• amocrm.createLead({ name, price?, pipeline_id?, status_id? } | Array<...>)
• amocrm.getContact({ id })
• amocrm.listContacts({ page?: number, limit?: number })
• amocrm.createContact({ name } | Array<...>)
• amocrm.createNote({ entity: 'leads'|'contacts'|'companies', payload: [...] })
• amocrm.exchangeAuthCode({ code, redirect_uri? })

Примеры

• Получить сделки:

{
  "tool": "amocrm.listLeads",


... [View full README on GitHub](https://github.com/grabarnick/amocrm-mcp-server#readme)