whatsapp-mcp

MCP-сервер к WhatsApp через шлюз GREEN-API. Даёт агенту чтение переписки (история чата, журналы входящих и исходящих, контакты, группы) и отправку сообщений и файлов.

Работает с обычным личным номером: номер один раз привязывается к инстансу GREEN-API по QR-коду в консоли шлюза, дальше никакого локального процесса и никакого повторного сканирования не нужно.

Зачем шлюз

Официальный WhatsApp Business Cloud API от Meta не даёт доступа к личной переписке и истории — только к диалогам, начатым после подключения бизнес-номера. Локальные мосты (whatsmeow, Baileys) требуют постоянно работающего процесса на машине пользователя. GREEN-API закрывает обе проблемы ценой платного тарифа и того, что под капотом у него неофициальный протокол.

Репозиторий пока лежит в личном пространстве eurogas-bbl, а не в brain-boost-academy: прав на создание репозиториев в организации нет. После переноса GitHub оставит редирект, и ссылки ниже продолжат работать.

Установка

Зависимостей, кроме uv, нет:

uvx --from git+https://github.com/eurogas-bbl/whatsapp-mcp whatsapp-mcp

Как запись в .mcp.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "uvx",
      "args": [
        "--env-file", "/путь/к/whatsapp-mcp.env",
        "--from", "git+https://github.com/eurogas-bbl/whatsapp-mcp",
        "whatsapp-mcp"
      ]
    }
  }
}

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

Токен не попадает в текст ошибок: он лежит в URL, а URL — в сообщениях httpx, поэтому перед выдачей модели он заменяется на ***.

Инструменты

Чтение — всегда:

get_state, get_settings, list_chats, get_chat_history, get_last_incoming_messages, get_last_outgoing_messages, get_contact_info, get_group_data, check_whatsapp, get_file_link, receive_notification, delete_notification.

Запись — если не выставлен WHATSAPP_READONLY:

send_message, send_file, send_file_by_url, mark_chat_read, set_settings.

delete_notification доступен и в режиме чтения: он убирает обработанное событие из очереди шлюза и ничего не меняет в самих чатах, а без него receive_notification бесконечно возвращает одно и то же.

Идентификаторы чатов

Личный чат — 79001234567@c.us, группа — 120363043968066561@g.us, скрытый номер — 123456789012345@lid. Голый номер телефона (79001234567, +7 (900) 123-45-67) достраивается до @c.us; для групп и @lid идентификатор нужно передавать целиком, потому что от номера они неотличимы.

Ограничения

• История видна только за то время, пока номер привязан к инстансу: GREEN-API не выгружает переписку, накопленную до подключения.

• У getChatHistory нет постраничного обхода — только count.

• Журналы входящих и исходящих и отметка прочитанным работают лишь при включённых уведомлениях инстанса: set_settings с incomingWebhook: yes, outgoingMessageWebhook: yes, outgoingAPIMessageWebhook: yes.

• Ответы обрезаются на 256 КБ, чтобы длинная переписка не вытеснила контекст; обрезанный ответ помечен полем truncated.

Разработка

uv sync
uv run pytest -q
uv run pyright

Тесты офлайн: HTTP замокан через httpx.MockTransport, инструменты вызываются настоящим MCP-клиентом.