> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP сервер

> Позвольте агентам AI использовать WhatsApp с помощью встроенного GOWA Model Context Protocol endpoint на /mcp.

GOWA служит конечной точке [Model Context Protocol](https://modelcontextprotocol.io) в том же процессе, что и REST API. Любой клиент MCP, поддерживающий **трансляцию HTTP**, может отправлять сообщения, читать и управлять группами через него.

* URL: `http://<host>:3000<APP_BASE_PATH>/mcp` (по умолчанию `http://localhost:3000/mcp`)
* Включено по умолчанию. Отключите при помощи `MCP_ENABLED=false` или `--mcp-enabled=false`.
* Stateless: нет сессионной рукопожатия для поддержания живых между звонками.

> [!NOTE]
>
> Обновление с старого релиза? Автономная команда `./whatsapp mcp` и её конечная точка SSE по порту 8080 (`/sse`) пропали. Запустите `./whatsapp rest` и указывает на клиентов `/mcp`. Старый одноинструмента-для операции был заменен консолидированными инструментами ниже.

## Подключить клиента

`/mcp` сидит за Базовым Авторизом, как REST API. Отправьте заголовок `Authorization` плюс `X-Device-Id`, если у вас несколько устройств:

```json theme={null}
{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic YWRtaW46Y2hhbmdlbWU=",
        "X-Device-Id": "my-device"
      }
    }
  }
}
```

`YWRtaW46Y2hhbmdlbWU=` это `base64("admin:changeme")`; генерируйте ваш с помощью `echo -n 'user:pass' | base64`. Если установлено только одно устройство, поместите `Authorization` и `X-Device-Id`.

Точный формат конфигурации зависит от клиента. Если клиент может запускать только stdio серверы, используйте мост, такой как `mcp-remote`.

## Инструменты

GOWA раскрывает семь инструментов. Каждый принимает аргумент `type` (send) или `action` (все остальные), который выбирает операцию.

| Инструмент | `type` / `action` значения |
| - | - |
| `whatsapp_send` | `text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `poll`, `link`, `forward` |
| `whatsapp_schedule` | `list`, `get`, `pause`, `resume`, `cancel` |
| `whatsapp_message` | `react`, `edit`, `revoke`, `delete`, `mark_read`, `mark_played`, `star`, `unstar`, `download_media` |
| `whatsapp_chat` | `list_chats`, `list_contacts`, `get_messages`, `archive` |
| `whatsapp_group` | `create`, `join_with_link`, `leave`, `info`, `participants`, `add_participants`, `remove_participants`, `promote`, `demote`, `invite_link`, `set_name`, `set_topic`, `set_settings`, `join_requests`, `manage_join_requests` |
| `whatsapp_app` | `status`, `login_qr`, `login_code`, `logout`, `reconnect` |
| `whatsapp_newsletter` | `follow`, `unfollow`, `info`, `directory`, `messages`, `message_updates`, `live_updates_subscribe`, `live_updates_unsubscribe`, `live_updates_list` |

Примечания к аргументам:

* `whatsapp_send` всегда нужен `type` и `phone`. Медиа отправляется **только по URL** (`image_url`, `video_url`, `audio_url`, `file_url`, `sticker_url`); MCP не может загружать локальные файлы. `link` нужен `link` и `caption`; `forward` нужен `message_id`.
* `whatsapp_send` принимает [поля расписания](https://gowa-docs.mintlify.site/ru/examples/scheduled-sends.md) (`scheduled_at`, `timezone`, `recurrence`, `weekdays`, `day_of_month`, `end_at`, `occurrence_limit`). Управление результатами с помощью `whatsapp_schedule` (`get`, `pause`, `resume` и `cancel` нужно `schedule_id`).
* `whatsapp_message` нужен `phone` (чат) и `message_id`; `edit` также нужен `message`.
* В GOWA `main` после v9.9.0, `whatsapp_message` с помощью `action: "edit"` принимает `media_type: "image"` или `media_type: "document"` для замены заголовка. Сопоставьте исходный тип файла и пропустите `link`. Смотрите [Изменить субтитры](https://gowa-docs.mintlify.site/ru/examples/sending-messages.md#%D1%80%D0%B5%D0%B4%D0%B0%D0%BA%D1%82%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D1%82%D1%8C-%D0%BF%D0%BE%D0%B4%D0%BF%D0%B8%D1%81%D1%8C-%D0%B8%D0%B7%D0%BE%D0%B1%D1%80%D0%B0%D0%B6%D0%B5%D0%BD%D0%B8%D1%8F-%D0%B8%D0%BB%D0%B8-%D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B0).
* `whatsapp_chat`: `get_messages` нужен `chat_jid`; `archive` нужен `chat_jid` и `archived`.
* `whatsapp_app`: `login_code` нужен `phone`.

Экспериментальные кнопки, запрос на размещение и отправка карусели доступны только через REST. [интерактивные сообщения](https://gowa-docs.mintlify.site/ru/examples/interactive-messages.md). Инструменты рассылки поддерживают поиск каналов и счетчики истории и автоматически обновляют подписку на live-обновления. Смотрите [newsletters](https://gowa-docs.mintlify.site/ru/examples/newsletters.md).

При загрузке медиа URL-адреса используются те же проверки публичного адреса, что и REST посылает и подключается напрямую без `HTTP_PROXY` или `HTTPS_PROXY`. Загрузка локальных файлов требует REST API.

Ваш клиент MCP показывает полную схему ввода каждого инструмента. Конечная точка HTTP принимает POST и DELETE. GET SSE стриминг отключен.

## Выбор устройства

Каждый вызов решает свое устройство в указанном порядке:

1. Аргумент `device_id` при вызове инструментов.
2. Заголовок `X-Device-Id` на MCP соединении.
3. Единственное зарегистрированное устройство, когда оно существует.

В противном случае звонок не выполняется с `device identification required: set the X-Device-Id header or pass device_id`. См. [Multi-device](https://gowa-docs.mintlify.site/ru/concepts/multidevice.md).

## Удаленные клиенты с OAuth

Hosted clients such as Claude custom connectors cannot add a Basic Auth header. Для них GOWA может запустить сервер авторизации OAuth 2.1 для `/mcp`. По умолчанию он отключен.

```env theme={null}
APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com
# optional, defaults to issuer + APP_BASE_PATH + /mcp
MCP_OAUTH_RESOURCE_URL=https://gowa.example.com/mcp
```

Требования и поведение:

* `APP_BASIC_AUTH` должен быть установлен: страница авторизации подписывает пользователей с этими же учетными записями. Без нее запуск не выполняется.
* Эмитент и ресурс должны быть **публичными HTTPS** URL, видимыми клиентами, а не внутренними адресами типа `http://gowa:3000`.
* С OAuth `/mcp` принимает токен Марера **или** Базовая Авто. Жетоны не принимаются на маршрутах REST или UI.
* Клиенты регистрируются (динамическая регистрация клиентов) с использованием RFC 7591, регистрационные органы ограничены 16 киБ и перенаправляют URI на 2 киБ. Регистрация ограничена 40 в час и 1000 неиспользованных клиентов после 24 часов.
* Использование PKCE `S256` обязательно. Срок действия кодов — 5 минут, токенов доступа — 1 час; токены обновления ротируются, а повторное использование старого токена отзывает всё семейство токенов. В `MCP_OAUTH_DB_URI` (по умолчанию `file:storages/oauth.db`) хранятся только SHA-256-хеши токенов.

URI перенаправления должны точно совпадать с зарегистрированными значениями. Нативные клиенты могут использовать HTTP-адреса обратного вызова с IP-адресом петлевого интерфейса и динамическим портом. Адреса обратного вызова с `localhost` требуют явно указанного порта и точного совпадения. Для остальных перенаправлений требуется HTTPS. Параметр OAuth `resource` привязан к каноническому URL MCP; в запросах токенов его можно опустить, но указанное значение должно совпадать. Успешные ответы авторизации содержат `iss`.

Устаревшие коды и токены обрабатываются во время записи OAuth. Повернутые хэши refresh-token сохраняются и необходимы для обнаружения перебоев с живой семьей, в течение почти одного последующего времени жизни до 30 дней. Удаление или замена базы данных OAuth лишает права существующих клиентов и грантов.

Конечные точки, относительно издателя: `/oauth/authorize`, `/oauth/token`, `/oauth/register`. Обнаруженные метаданные используют известные URL в корне домена, поэтому с `APP_BASE_PATH=/gowa` ваш прокси должен маршрутизировать:

```text theme={null}
https://gowa.example.com/.well-known/oauth-authorization-server/gowa
https://gowa.example.com/.well-known/oauth-protected-resource/gowa/mcp
```

Проверить обнаружение снаружи:

```bash theme={null}
curl -i -X POST https://gowa.example.com/mcp          # expect 401 with a Bearer challenge
curl https://gowa.example.com/.well-known/oauth-protected-resource/mcp
curl https://gowa.example.com/.well-known/oauth-authorization-server
```

Затем добавьте `https://gowa.example.com/mcp` в качестве пользовательского коннектора и войдите в аккаунт `APP_BASIC_AUTH`.

> [!WARNING]
>
> Убедитесь, что Cloudflare Access, боты или прокси авторизации перед GOWA не могут перехватывать известные пути `/oauth/*` или `/mcp`. Ограничение неудачных входов на `/oauth/authorize` на вашем прокси.


## Related topics

- [Запланированные отправители](https://gowa-docs.mintlify.site/ru/examples/scheduled-sends.md)
- [Справочник по API](https://gowa-docs.mintlify.site/ru/api-reference/introduction.md)
- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/ru/index.md)
- [Ссылка на конфигурацию](https://gowa-docs.mintlify.site/ru/configuration.md)
- [Аутентификация API](https://gowa-docs.mintlify.site/ru/api-reference/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.