# Подключение SmmBox к ИИ-ассистенту (MCP)

MCP — открытый стандарт, через который ИИ-ассистенты подключаются к внешним сервисам.
Подключите SmmBox к своему ассистенту (Claude, Codex, Cursor, VS Code, n8n и другим), и он сможет
сам смотреть ваши группы и расписание, планировать, редактировать и удалять посты —
по обычной просьбе в чате.

Например:

- "Покажи мои группы в SmmBox"
- "Какие посты запланированы во ВКонтакте на эту неделю?"
- "Найди 3 свободных слота в расписании группы и запланируй туда эти тексты"
- "Перенеси завтрашний пост на 18:00 по Москве"
- "Покажи посты, которые не опубликовались из-за ошибки"

## Что понадобится

1. **Тариф с доступом к API**: Эксперт, Бизнес или Персональный.
2. **Ключ API** — его выдаёт раздел "API и MCP" в SmmBox (см. шаг 1).
3. **ИИ-клиент, который подключает удалённые MCP-серверы по ключу в заголовке** — примеры
   настройки ниже. Клиенты, которые подключаются только через вход по OAuth, пока не подойдут.

Параметры подключения для любого клиента:

| Параметр | Значение |
|---|---|
| Адрес | `https://smmbox.com/mcp/` — **слэш в конце обязателен** |
| Транспорт | Streamable HTTP (в настройках часто называется `http`, не `sse`) |
| Заголовок | `Authorization: Bearer <ваш ключ>` |

## Шаг 1. Получите ключ

1. Откройте в меню **Автоматизация → API и MCP**.
2. Нажмите **"Создать ключ"**.
3. Укажите имя (например, `claude`) и срок действия — месяц, 3 месяца, год или бессрочно.
4. Нажмите **"Сгенерировать"** и скопируйте ключ. Он начинается с `sbx.1`.

Полностью ключ показывается **только один раз**. В списке ключей остаются лишь его первые и
последние символы. Если ключ потерялся, создайте новый, а старый отзовите.

Ключ даёт доступ к вашим постам так же, как вход в аккаунт. Не публикуйте его, не пересылайте
в мессенджерах и не выкладывайте файлы настроек с ключом в общий доступ (например, на GitHub).

## Шаг 2. Подключите ассистента

Во всех примерах замените `sbx.1ВАШ_КЛЮЧ` на свой ключ. После правки файла настроек
перезапустите приложение.

### Claude Code

Выполните в терминале:

```bash
claude mcp add --transport http smmbox https://smmbox.com/mcp/ --header "Authorization: Bearer sbx.1ВАШ_КЛЮЧ"
```

Проверка: `claude mcp list` — у `smmbox` должно быть `Connected`.

### Codex

Работает в Codex на компьютере: в терминале, расширении для редактора и приложении.
Ключ хранится в переменной окружения, а не в файле настроек.

1. Добавьте переменную окружения `SMMBOX_TOKEN` со своим ключом. Для текущего сеанса терминала:

```bash
export SMMBOX_TOKEN="sbx.1ВАШ_КЛЮЧ"
```

   Чтобы не вводить заново, добавьте эту строку в `~/.zshrc` или `~/.bashrc`.

2. Подключите сервер:

```bash
codex mcp add smmbox --url https://smmbox.com/mcp/ --bearer-token-env-var SMMBOX_TOKEN
```

   Или добавьте вручную в `~/.codex/config.toml`:

```toml
[mcp_servers.smmbox]
url = "https://smmbox.com/mcp/"
bearer_token_env_var = "SMMBOX_TOKEN"
```

### Claude Desktop

Claude Desktop подключает такой сервер через посредника `mcp-remote`. Для него нужен
установленный [Node.js](https://nodejs.org/) версии 18 или новее.

1. Откройте **Настройки → Developer → Edit Config**. Откроется файл `claude_desktop_config.json`:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. Добавьте в него:

```json
{
  "mcpServers": {
    "smmbox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://smmbox.com/mcp/",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer sbx.1ВАШ_КЛЮЧ"
      }
    }
  }
}
```

Если в файле уже есть другие серверы, добавьте блок `"smmbox"` внутрь существующего `"mcpServers"`.
Пробела после двоеточия в `Authorization:${AUTH_HEADER}` быть не должно — так значение
корректно передаётся и на Windows.

3. Полностью закройте Claude Desktop и откройте снова.

### Cursor

Откройте **Settings → MCP → Add new MCP server** или создайте файл `~/.cursor/mcp.json`
(для одного проекта — `.cursor/mcp.json` в его папке):

```json
{
  "mcpServers": {
    "smmbox": {
      "url": "https://smmbox.com/mcp/",
      "headers": {
        "Authorization": "Bearer sbx.1ВАШ_КЛЮЧ"
      }
    }
  }
}
```

### VS Code (GitHub Copilot)

Создайте в папке проекта файл `.vscode/mcp.json`. В этом варианте ключ не хранится в файле:
VS Code спросит его при первом запуске сервера.

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "smmbox-key",
      "description": "Ключ API SmmBox",
      "password": true
    }
  ],
  "servers": {
    "smmbox": {
      "type": "http",
      "url": "https://smmbox.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${input:smmbox-key}"
      }
    }
  }
}
```

Инструменты SmmBox доступны в чате Copilot в режиме агента.

### n8n

1. Добавьте к узлу **AI Agent** инструмент **MCP Client Tool**.
2. **Endpoint**: `https://smmbox.com/mcp/`.
3. **Server Transport**: `HTTP Streamable`.
4. **Authentication**: `Bearer Auth`. В новых учётных данных укажите ключ — сам ключ,
   без слова `Bearer`.

### Другие клиенты

Подойдёт любой клиент, где для удалённого MCP-сервера можно указать адрес и заголовок
`Authorization`. Используйте параметры из таблицы в начале инструкции.

## Шаг 3. Проверьте подключение

Попросите ассистента: **"Покажи мои группы в SmmBox"**. Он должен вывести список ваших
сообществ и страниц. Если вместо этого ошибка — см. раздел "Если не работает".

## Что умеет ассистент

| Возможность | Что это значит |
|---|---|
| Группы | список подключённых сообществ и страниц |
| Проекты | список проектов и групп в них |
| Расписание | календарь публикаций группы или проекта и его метки |
| Свободные даты | ближайшие свободные слоты по календарю или с заданным интервалом |
| Посты | список постов с фильтрами: группа, соцсеть, статус (запланирован, опубликован, ошибка), период |
| Один пост | содержимое и настройки конкретного поста |
| Создание | создание одного или сразу нескольких постов |
| Изменение | правка запланированного поста или поста с ошибкой |
| Удаление | удаление одного или нескольких постов |

Ассистент работает от вашего имени: видит ваши посты и посты ваших команд и публикует
только в подключённые вами группы. Чужие данные ему недоступны.

## Что важно знать

- **Удаление убирает пост только из SmmBox.** Если пост уже опубликован, в соцсети он останется.
  Удалённый пост не восстановить — попросите ассистента показать список постов и подтвердить
  удаление, прежде чем удалять.
- **Опубликованный пост изменить нельзя.** Правятся только запланированные посты и посты с ошибкой.
- **Пачка постов создаётся целиком или не создаётся вовсе.** Если хотя бы один пост не прошёл
  проверку, не будет создан ни один — ассистент получит ошибку и сможет исправить запрос.
- **Дата публикации — только в будущем.** Называйте время с часовым поясом ("в 18:00 по Москве"),
  чтобы ассистент не ошибся.
- **Свободные слоты не бронируются.** Ассистент получает подходящие даты, но место в расписании
  занимает только созданный пост.
- **Фото и видео — по публичной ссылке.** Загрузить файл с компьютера через ассистента нельзя:
  дайте ему ссылку на картинку или видео в интернете.
- **Маркировка рекламы недоступна** — пометить пост как рекламный через ассистента нельзя.
- **Есть ограничение на частоту запросов** — общее для API и MCP:

| Тариф | в секунду | в минуту | в час | в сутки |
|---|---|---|---|---|
| Эксперт | 3 | 50 | 1 000 | 15 000 |
| Бизнес, Персональный | 6 | 100 | 2 000 | 30 000 |

  Обычной работы в чате это не касается. При превышении ассистент получит ошибку
  "Превышено количество запросов" — достаточно немного подождать.

## Если не работает

| Что видите | Что сделать |
|---|---|
| Ошибка 401 ("Unauthorized" или "Authentication required") | Проверьте, что ключ скопирован целиком, без пробелов и переносов строки, и перед ним стоит `Bearer `. Ключ мог истечь или быть отозван — создайте новый. |
| 401 при верном ключе | Проверьте тариф: доступ есть на тарифах Эксперт, Бизнес и Персональный. |
| Пустой ответ или ошибка при подключении | Проверьте адрес: `https://smmbox.com/mcp/` со слэшем в конце. Тип подключения — `http` (Streamable HTTP), не `sse`. |
| Claude Desktop не видит сервер | Проверьте, что установлен Node.js 18+ и JSON в файле настроек без ошибок; полностью перезапустите приложение. |
| "Превышено количество запросов" | Подождите минуту и повторите. |
| Ассистент не находит группу | Группа должна быть подключена в SmmBox. Попросите ассистента сначала вывести список групп. |
| "Вы указали дату, которая уже прошла" | Укажите время в будущем, с часовым поясом. |

## Как отозвать ключ

Откройте **Автоматизация → API и MCP**, найдите ключ в списке "Ваши ключи" и нажмите
**"Отозвать"**. Ассистент сразу потеряет доступ. Чтобы подключить его снова, создайте новый
ключ и замените старый в настройках клиента.

## Документация

Справка по API, на котором работает MCP: https://smmbox.com/api/
