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",
  "arguments": { "page": 1, "limit": 25 }
}

• Создать сделку:

{
  "tool": "amocrm.createLead",
  "arguments": { "name": "Новая сделка", "price": 10000 }
}

• Получить контакт:

{
  "tool": "amocrm.getContact",
  "arguments": { "id": 123456 }
}

Тестирование

Тестирование MCP сервера

После сборки вы можете протестировать MCP сервер несколькими способами:

Метод 1: MCP Inspector (рекомендуется)

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Inspector откроет веб-интерфейс, где вы сможете:

• Просмотреть все инструменты
• Тестировать вызовы
• Отлаживать ошибки

Метод 2: Claude Desktop

Подключите сервер к Claude Desktop (см. раздел "Подключение MCP-клиента" выше).

Подробнее: TEST-MCP.md

Тестирование API отдельно от MCP

Вы можете тестировать методы работы с AmoCRM API независимо от MCP сервера:

# Показать справку
npm run test-api

# Получить информацию об аккаунте
npm run test-api account

# Получить список сделок
npm run test-api leads 10

# Создать сделку
npm run test-api create-lead "Тестовая сделка"

Или используйте удобный скрипт:

./api-test.sh account
./api-test.sh leads 5

Подробная документация по тестированию

• TEST-MCP.md - Тестирование MCP сервера
• TEST-API.md - Тестирование AmoCRM API
• OAUTH-GUIDE.md - Руководство по OAuth авторизации
• DO-TOKEN-AUTO-UPDATE.md - 🆕 Автообновление токенов на DigitalOcean
• TESTING-GUIDE.md - Полное руководство по тестированию

Продвинутые примеры

В директории examples/ находятся примеры для специфических сценариев:

• advanced-test.ts - создание сделок с контактами, поиск, обновление, добавление примечаний

Ссылки

• Документация amoCRM (возможности и API): https://www.amocrm.ru/developers/content/crm_platform/platform-abilities