instagram-mcp

Удаленный MCP-сервер, который позволяет каждому участнику команды публиковать карусели и одиночные изображения в Instagram прямо из диалога с Claude — в свой собственный профессиональный аккаунт Instagram, и ни в чей другой.

Токен-носитель идентифицирует человека. Этот человек соответствует ровно одному аккаунту Instagram в базе данных. Ни один инструмент никогда не принимает идентификатор аккаунта Instagram в качестве параметра, поэтому публикация в аккаунт коллеги путем передачи неверного идентификатора структурно невозможна.

Приложение Meta работает в режиме разработки, и каждый участник команды добавлен как тестер Instagram — никакого обзора приложений Meta, никакого процесса входа через OAuth, никакого перехода в Live. Это сделано намеренно.

Подключение к Claude (отправьте этот раздел коллеге как есть)

Вам понадобятся две вещи от администратора: URL сервера и ваш личный токен доступа (начинается с igmcp_). Храните токен как пароль — любой, кто им владеет, может публиковать в ваш аккаунт Instagram.

1. В Claude откройте Настройки → Соединители → Добавить пользовательский соединитель.

2. Вставьте этот URL:

   https://YOUR-DEPLOYMENT.vercel.app/api/mcp

   (администратор даст вам реальное имя хоста)

3. Там, где соединитель запрашивает аутентификацию, добавьте этот заголовок — Имя слева, значение справа:

   Authorization: Bearer igmcp_your_token_here

   Имя заголовка: Authorization. Значение заголовка: слово Bearer, пробел, затем ваш токен. Больше ничего.

4. Сохраните. В любом диалоге вы теперь можете сказать, например, "опубликуй эти 5 слайдов как карусель с этой подписью", и Claude загрузит изображения и опубликует их в ваш аккаунт.

Что вы можете попросить Claude сделать:

• Опубликовать карусель (2–10 изображений, одна подпись для всего поста)

• Опубликовать одиночное изображение

• Проверить, сколько постов у вас осталось на сегодня (Instagram ограничивает публикацию через API до 100 за 24 часа)

• Проверить состояние вашего токена (ваше подключение к Instagram автоматически обновляется задолго до истечения срока; это покажет, если что-то не так)

• Показать список ваших последних постов (только ваших)

Если публикация не удалась на полпути, просто попросите Claude повторить ту же публикацию — сервер продолжит с того места, где остановился, и не создаст дубликат.

Онбординг нового участника команды (администратор)

Предварительные требования, один раз на человека:

1. Его аккаунт Instagram должен быть профессиональным аккаунтом (Business или Creator).

2. На developers.facebook.com откройте приложение Meta → Instagram → API setup with Instagram Login → добавьте его аккаунт как тестера Instagram. Он должен принять приглашение (приложение Instagram → Настройки → Разрешения веб-сайтов → Приложения и веб-сайты → Приглашения тестера).

3. Сгенерируйте долгоживущий токен доступа для его аккаунта из панели управления приложением (кнопка "Generate token" рядом с аккаунтом тестера). Скопируйте токен и запишите идентификатор пользователя аккаунта.

Затем добавьте его в систему (с вашей машины, в этом репозитории, с заполненным .env.local):

npm run add-member -- --name "Ada" --ig-user-id 17840000000000000 --ig-username ada.builds
# pastes the long-lived IG token when prompted (kept out of shell history)

Скрипт проверяет токен в реальном времени через graph.instagram.com, отказывается добавлять, если токен принадлежит другому аккаунту, отличному от переданного вами идентификатора, и выводит токен-носитель igmcp_ участника один раз. Отправьте его участнику по защищенному каналу вместе с разделом "Подключение к Claude" выше.

Чтобы отозвать доступ: установите revoked_at = now() в строке участника в таблице team_members. Его токен начнет возвращать 401 немедленно.

Архитектура

instagram-mcp/
├── api/
│   ├── mcp.ts                 # MCP endpoint (Streamable HTTP), bearer auth wrapper
│   └── cron/refresh-tokens.ts # Vercel Cron target (daily; refreshes tokens nearing expiry)
├── src/
│   ├── auth.ts                # bearer lookup → resolves the calling member
│   ├── crypto.ts              # AES-256-GCM for IG tokens, SHA-256 for bearer hashes
│   ├── instagram.ts           # containers, polling, publish, refresh, idempotent resume
│   ├── storage.ts             # R2 uploads (per-member key prefix)
│   ├── db.ts                  # Supabase (service role)
│   ├── refresh.ts             # refresh loop shared by cron + CLI
│   └── tools/                 # one file per tool
├── scripts/
│   ├── add-member.ts          # seeds a member, generates their bearer token
│   └── refresh-tokens.ts      # manual run of the refresh loop
├── supabase/migrations/       # schema (already applied via the Supabase connector)
├── .env.example               # every key, documented
└── README.md

Ключевые решения:

• Транспорт: mcp-handler v2 (MCP-адаптер Vercel) с @modelcontextprotocol/server v2 — только Streamable HTTP; устаревший транспорт HTTP+SSE был удален в вышестоящей версии v2, что именно нам и нужно. Никакого самодельного транспорта.

• Хост: все общается с https://graph.instagram.com (путь Instagram Login). graph.facebook.com относится к пути Facebook Login и выдает вводящую в заблуждение ошибку парсинга токена — большинство руководств ошибаются в этом.

• Аутентификация: Authorization: Bearer <token> в каждом запросе. Токен хэшируется (SHA-256), ищется и повторно проверяется с помощью сравнения за постоянное время; неизвестные и отозванные токены возвращают 401 до любой обработки. Токены Instagram хранятся в Postgres, зашифрованные AES-256-GCM; токены-носители никогда не хранятся в исходном виде.

• Идемпотентность: ключ идемпотентности (участник + URL изображений + подпись) записывается в таблицу posts до любого вызова Meta. Идентификаторы дочерних контейнеров сохраняются по мере их создания. При повторной попытке используются ЗАВЕРШЕННЫЕ дочерние элементы, пересоздаются только ОШИБОЧНЫЕ, а повторная публикация того же родительского контейнера безопасна (media_publish идемпотентен для каждого контейнера) — таким образом, полуопубликованная карусель никогда не может быть дублирована.

• Обновление токена: Cron Vercel запускается ежедневно; токены действуют 60 дней, и каждый обновляется, как только попадает в 25-дневное окно обновления, так что неудачный запуск получает новую попытку каждые 24 часа, а не одну попытку в месяц. Сбой одного участника не прерывает цикл; постоянные сбои (отозванный доступ, изменение типа аккаунта) помечают строку и отображаются через check_token_health вместо бесконечных повторных попыток.

Развертывание (администратор)

npm install
npm run typecheck && npm test     # 19 unit tests, live tests skip without creds

vercel login
vercel link                        # or create the project
# Set every var from .env.example in Vercel → Project → Settings → Environment Variables
vercel --prod

Затем поместите URL развертывания в раздел "Подключение к Claude" выше.

Supabase должен быть выделенным проектом, который размещает только этот сервер — не проектом, общим с другим приложением. team_members и posts — это общие имена, и клиент с ролью обслуживания имеет полный доступ к таблицам, поэтому совместное использование схемы с несвязанным продуктом представляет риск коллизии (и зоны поражения). Создайте проект под своей собственной учетной записью, затем примените миграцию в supabase/migrations/ через редактор SQL или MCP-соединитель Supabase.

Для корзины R2 требуется включить публичный доступ (пользовательский домен или r2.dev), соответствующий R2_PUBLIC_BASE_URL.

Приемочные тесты в реальном времени

С заполненным .env.local и хотя бы одним добавленным участником:

LIVE_MEMBER_BEARER_TOKEN=igmcp_...            npm test   # upload + token health, no posting
LIVE_MEMBER_BEARER_TOKEN=igmcp_... LIVE_PUBLISH=1 npm test   # ⚠ creates REAL posts
# add LIVE_MEMBER_BEARER_TOKEN_2=igmcp_... for the two-members-two-accounts test

Эксплуатационные заметки

• Тихий режим отказа №1 — истекший токен — публикация прекращается, и никто не замечает. Cron отмечает сбои громко (не-200 → красный запуск в панели управления Vercel), а check_token_health сообщает количество дней до истечения и сбои обновления для каждого участника.

• Instagram ограничивает публикацию до 100 постов на аккаунт за скользящие 24 часа; get_publishing_limit считывает текущий счетчик.

• Контейнеры истекают через ~24 часа, и есть ограничение примерно в 50 ожидающих контейнеров на аккаунт — еще одна причина, по которой путь повторных попыток использует существующие контейнеры вместо создания новых.

• Сохраняйте слайды карусели одинакового соотношения сторон; Instagram обрезает все под первый слайд. Только JPEG/PNG, не более 8 МБ.