mcp-insta

Локальный MCP-сервер для Windows, который безопасно подключает один профессиональный Instagram Creator/Business аккаунт к AI-клиенту через Meta Graph API.

Он рассчитан на работу с одной заранее выбранной связкой Facebook Page → Instagram. Секреты и access token остаются в Windows Credential Manager; SQLite хранит только техническую привязку аккаунта и Page.

Что умеет

ig_direct_reply_prepare создаёт одноразовую операцию и ничего не отправляет. Только отдельный вызов ig_direct_reply_confirm выполняет отправку. Срок действия подготовленной операции — пять минут.

Как устроено

flowchart LR
  User["Пользователь"] --> Client["MCP-клиент"]
  Client --> Runtime["mcp-insta"]
  Runtime --> Auth["OAuth + PKCE"]
  Auth --> Credentials["Windows Credential Manager"]
  Runtime --> State["SQLite: IDs аккаунта и Page"]
  Runtime --> Graph["Meta Graph API"]
  Runtime --> Messaging["Instagram Messaging API"]
  Runtime --> Gates["Capability gates"]
  Gates --> Reads["Профиль, медиа, аналитика, Direct"]
  Runtime --> Prepare["Подготовка ответа"]
  Prepare --> Confirm["Явное подтверждение"]

Расширенная схема: docs/architecture/project-graph.mmd.

.
├── docs/                  # настройка Meta, Windows и матрица возможностей
├── scripts/               # сборка и подготовка пакета
├── src/
│   ├── auth/              # OAuth + PKCE и выбор Page → Instagram
│   ├── direct/            # ссылки и Direct workflow
│   ├── meta/              # Graph и Page Messaging клиенты
│   ├── secrets/           # Windows Credential Manager
│   ├── storage/           # локальная SQLite-привязка
│   └── tools/             # MCP-инструменты
└── tests/                 # unit и интеграционные проверки

Быстрый старт

Нужны Windows и Node.js 22.5 или новее.

npm ci
npm run build

Добавьте собранный сервер в конфигурацию MCP-клиента:

{
  "mcpServers": {
    "insta": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-insta\\dist\\index.js"]
    }
  }
}

Настройка Meta и подключение

1. Создайте Meta App с Facebook Login for Business.

2. Свяжите профессиональный Instagram Creator/Business аккаунт с отдельной Facebook Page.

3. Добавьте redirect URI http://localhost:8787/callback.

4. В Windows Credential Manager создайте generic credentials mcp-insta/app-id и mcp-insta/app-secret.

5. Вызовите insta_auth_start, завершите OAuth в браузере, затем вызовите insta_auth_complete.

6. Запустите insta_diagnose: он открывает каждую возможность только после успешной API-проверки именно этой связки аккаунтов.

Полная инструкция: настройка Windows, настройка Meta, матрица возможностей.

Границы безопасности

• App ID, App Secret и access token не попадают в .env, SQLite, логи или ответы MCP.

• Cookie и тексты Direct не сохраняются локально.

• OAuth закрепляет ровно одну выбранную связку Page → Instagram; неоднозначный результат отклоняется.

• Ошибки очищаются от токенов и параметров URL.

• Перед Graph-запросами проверяются capability gates, формат ID и совместимость метрик с endpoint.

• Подтверждение Direct-ответа — единственная исходящая операция. Публикация, отправка сообщений одним вызовом и модерация комментариев не реализованы.

Превью

Собирает важное из Instagram, чтобы слышать аудиторию внимательнее.

Проверка

npm run check
npm pack --dry-run --json

Набор тестов проверяет OAuth с PKCE, привязку Page → Instagram, хранение и редактирование секретов, capability gates, MCP-протокол, безопасные ошибки, Graph read API, пагинацию, аналитику и контракт Direct prepare → confirm.

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

• Технический аудит

• Приёмка первого релиза

• Настройка Windows

• Настройка Meta

• Матрица совместимости

Лицензия

MIT

• 2026-07-20 · 28d951c · docs: add README history and project slogan · Открыть редакцию

• 2026-07-20 · 07b8e7d · docs: redesign README with verified preview · Открыть редакцию

• 2026-07-20 · f600005 · feat: establish secure Instagram MCP · Открыть редакцию