# amoCRM MCP

MCP-сервер для [amoCRM](https://www.amocrm.ru/). Даёт ИИ-агентам (Claude Code, Claude Desktop, Cursor, Cline, Windsurf и любому MCP-клиенту) доступ к вашему аккаунту amoCRM: сделки, контакты, компании, примечания и переписки, задачи, связи между сущностями, теги и кастомные поля — плюс универсальный инструмент для вызова любого эндпоинта API.

Запускается локально по stdio, работает на чистом Node.js.

## Возможности

**29 инструментов**, покрывающих основной REST API v4:

| Категория | Инструменты |
|-----------|-------------|
| Аккаунт | `get_account`, `list_pipelines`, `list_users` |
| Сделки | `list_leads`, `get_lead`, `create_lead`, `update_lead` |
| Контакты | `list_contacts`, `get_contact`, `create_contact`, `update_contact` |
| Компании | `list_companies`, `get_company`, `create_company`, `update_company` |
| Активности | `list_notes`, `add_note`, `add_call_note`, `add_service_message`, `list_events` |
| Задачи | `create_task` |
| Связи | `link_entities`, `unlink_entities`, `list_links` |
| Теги | `list_tags`, `add_tags` |
| Поля | `list_custom_fields`, `set_custom_field` |
| Универсальный | `amocrm_request` — любой GET/POST/PATCH/DELETE на любой путь API |

Инструмент `amocrm_request` гарантирует полное покрытие: если готового инструмента под задачу нет, агент всё равно сможет выполнить нужное действие.

## Требования

- [Node.js](https://nodejs.org/) 18 или новее (в комплекте идёт `npx`)
- Установленный `git` (нужен для запуска прямо из GitHub)
- Аккаунт amoCRM и долгоживущий токен доступа (см. ниже)

## Быстрый старт (в одну команду)

Клонировать репозиторий вручную не нужно — `npx` сам скачает и запустит сервер прямо из GitHub. Достаточно указать эту команду запуска в MCP-клиенте:

```bash
npx -y github:ivan000vovanov/amocrm-mcp
```

Конкретные команды для Claude Code, Claude Desktop и Cursor — ниже.

## Установка вручную (по желанию)

Если хотите держать код локально (например, чтобы дорабатывать):

```bash
git clone https://github.com/ivan000vovanov/amocrm-mcp.git
cd amocrm-mcp
npm install
```

Тогда в командах ниже вместо `npx -y github:ivan000vovanov/amocrm-mcp` используйте `node /абсолютный/путь/amocrm-mcp/src/index.js`.

## Как получить токен amoCRM

Нужен долгоживущий токен приватной интеграции:

1. Войдите в amoCRM → **Настройки** → **Интеграции**.
2. Нажмите **Создать интеграцию** → выберите **Внешнюю** (приватную) интеграцию.
3. Задайте название и права доступа (нужен доступ к CRM), сохраните.
4. Откройте созданную интеграцию → вкладка **Ключи и доступы**.
5. Выпустите **долгосрочный токен** (long-lived access token) — скопируйте его.

Ваш `AMOCRM_BASE_URL` — это адрес аккаунта, например `https://example.amocrm.ru`.

> Токен даёт полный доступ к CRM. Храните его в секрете и никогда не коммитьте в git.

## Настройка в клиентах

Во всех примерах подставьте свой адрес аккаунта и токен.

### Claude Code

```bash
claude mcp add amocrm \
  --env AMOCRM_BASE_URL=https://example.amocrm.ru \
  --env AMOCRM_TOKEN=ваш_токен \
  -- npx -y github:ivan000vovanov/amocrm-mcp
```

### Claude Desktop

Откройте файл конфигурации:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Добавьте сервер:

```json
{
  "mcpServers": {
    "amocrm": {
      "command": "npx",
      "args": ["-y", "github:ivan000vovanov/amocrm-mcp"],
      "env": {
        "AMOCRM_BASE_URL": "https://example.amocrm.ru",
        "AMOCRM_TOKEN": "ваш_токен"
      }
    }
  }
}
```

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

### Cursor

`Settings` → `MCP` → `Add new MCP server`, либо отредактируйте `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "amocrm": {
      "command": "npx",
      "args": ["-y", "github:ivan000vovanov/amocrm-mcp"],
      "env": {
        "AMOCRM_BASE_URL": "https://example.amocrm.ru",
        "AMOCRM_TOKEN": "ваш_токен"
      }
    }
  }
}
```

### Cline / Windsurf и другие

Любой MCP-клиент, поддерживающий stdio, настраивается так же: команда `npx` с аргументами `-y github:ivan000vovanov/amocrm-mcp` (или `node` + путь к `src/index.js` при ручной установке) и переменные окружения `AMOCRM_BASE_URL` и `AMOCRM_TOKEN`.

## Локальная проверка

Убедитесь, что сервер запускается и отдаёт список инструментов:

```bash
AMOCRM_BASE_URL=https://example.amocrm.ru \
AMOCRM_TOKEN=ваш_токен \
node src/index.js
```

Сервер выведет в stderr `stdio server started` и будет ждать команды по stdin.

## Примеры запросов агенту

- «Покажи последние 10 сделок в основной воронке»
- «Создай компанию ООО Ромашка с телефоном +7 900 000-00-00 и привяжи к ней новый контакт Иван»
- «Добавь примечание к сделке 12345: клиент просил перезвонить завтра»
- «Заведи задачу перезвонить по сделке 12345 на завтра в 10:00»
- «Найди контакт по имени Пётр и покажи связанные с ним сделки»

## Безопасность

- Токен читается только из переменных окружения — в коде его нет.
- Файл `.env` и `node_modules` исключены через `.gitignore`.
- Сервер работает локально; данные не отправляются никуда, кроме API amoCRM.

## Лицензия

MIT — см. [LICENSE](./LICENSE).