Instagram Analytics MCP

MCP-сервер, который отвечает на вопросы о производительности рилс в Instagram на естественном языке, для нескольких аккаунтов.

Смысл не в том, что он оборачивает API. А в том, что числа, которое действительно предсказывает охват, не существует в Instagram API, поэтому сервер вычисляет его.

"How did my last 10 reels do?"
"What worked best this month?"
"Which of my accounts is working?"

Какую проблему это решает

Instagram Graph API возвращает просмотры, охват, сохранения, репосты и среднее время просмотра.

Но он не возвращает процент досмотров — долю видео, которую люди реально смотрят. На реальном аккаунте, измеренном на ~700 рилс, именно досматриваемость отличает рилс, который умер, от того, который разлетелся:

Просмотры — это результат. Досматриваемость — причина, и её можно увидеть в течение нескольких часов после публикации, а не дней.

Для вычисления нужно avg_watch_time / duration. Длительности тоже нет в API. Поэтому сервер опрашивает media_url каждого видео с помощью ffprobe, чтобы измерить её.

Именно ради этого всё и существует. Два перехода, которые API за вас не сделает, плюс пороговое суждение, о котором у API нет мнения.

Инструменты

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

Работает с одним аккаунтом или несколькими. account необязателен и по умолчанию используется первый настроенный аккаунт.

Требования

• Профессиональный аккаунт Instagram (Бизнес или Автор). Личные аккаунты вообще не могут использовать Instagram API

• Python 3.10+

• ffprobe (brew install ffmpeg) — без него нет длительности, а значит, и процента досмотров

Настройка

git clone https://github.com/sskghub/instagram-analytics-mcp
cd instagram-analytics-mcp

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

cp .env.example .env

Затем получите токен. SETUP.md — это полное руководство, около 15 минут на первый аккаунт: создайте приложение Meta, добавьте Instagram, сгенерируйте токен.

Как только токен появится в .env, это проверит всё и сообщит вам id аккаунта, который нужно вставить обратно, чтобы вам не пришлось его искать:

.venv/bin/python check_setup.py

[  OK  ] mcp package installed
[  OK  ] ffprobe found
[  OK  ] main: token works, account @yourhandle

Затем убедитесь, что он получает реальные данные и что слой MCP работает насквозь:

.venv/bin/python server.py --selftest
.venv/bin/python test_server.py

Зарегистрируйте в Claude Code:

claude mcp add ig-analytics -- /absolute/path/.venv/bin/python /absolute/path/server.py

Сервер читает собственный .env, поэтому никакие учётные данные не попадают в конфигурационный файл MCP. Этот конфиг коммитится; токены — нет.

Добавление ещё одного аккаунта означает добавление двух строк в .env. Никакой код править не нужно — аккаунты обнаруживаются по именам переменных.

Срок действия токена

Токены Instagram действуют ~60 дней. Когда один умирает, всё нижестоящее молча возвращает пустоту.

refresh_tokens.py обменивает ещё действующий токен на новый 60-дневный:

python refresh_tokens.py --if-older-than 7

Запускайте еженедельно. Ограничение, которое формирует дизайн: просроченный токен невозможно обновить. Meta не продлит мёртвый токен, так что раннее обновление — единственная рабочая стратегия. Каждое обновление сбрасывает полные 60 дней, так что ранние обновления ничего не стоят.

Заметки по расписанию, включая ловушку macOS, когда фоновое задание launchd молча не может прочитать ваши файлы, — в SETUP.md.

Перед записью создаётся резервная копия .env, перезаписываются дублирующиеся ключи, а при сбое отправляется оповещение.

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

Заметки по разработке

Вещи, на которые ушло реальное время, сохранены здесь, потому что они обобщаются.

sys.exit() — это нормально в CLI и фатально в сервере. Первая версия переиспользовала функцию из существующего скрипта командной строки. Эта функция вызывала sys.exit(), когда токен отклонялся, что убило бы весь серверный процесс в день истечения срока действия токена. Теперь инструменты вызывают ValueError; SDK превращает стандартные исключения в читаемые результаты, на которые модель может реагировать, а сервер выживает.

В сообщениях об ошибках должно быть сказано, что делать. Мёртвый токен возвращает шаги по его перегенерации, а не трассировку стека. Модель может передать это человеку, который реально может это исправить.

Docstring — это интерфейс. Именно по нему модель решает, вызывать ли инструмент вообще, поэтому в каждом указано, когда к нему обращаться, а не только что он возвращает.

Плановые задания могут молча сбоить. На macOS таймер launchd для скрипта обновления падал с ошибкой Operation not permitted, потому что TCC блокирует фоновым агентам чтение защищённых каталогов. Он сообщал, что загружен, и мог бы тихо никогда не запуститься. Принудительный запуск и чтение журнала — единственный способ это обнаружить.

Дублирующиеся ключи в .env — настоящая ловушка. Устаревший дубликат может перекрыть свежезаписанный токен в зависимости от того, как загрузчик их разрешает, поэтому писатель перезаписывает все вхождения, а не первое.

API сменил имена. Это mcp.server.mcpserver.MCPServer; более старый путь mcp.server.fastmcp.FastMCP был удалён в mcp 2.x вместе с другими устаревшими модулями. Большинство примеров в интернете до сих пор показывают старый импорт и не будут работать.

Лицензия

MIT