Instagram Analytics MCP

여러 계정의 Instagram 릴 성과에 대해 자연어로 답변하는 MCP 서버입니다.

핵심은 API를 래핑하는 것이 아니라, 도달을 실제로 예측하는 숫자가 Instagram API에 존재하지 않기 때문에 서버가 직접 계산한다는 점입니다.

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

이 서버가 해결하는 문제

Instagram Graph API는 조회수, 도달, 저장, 공유, 평균 시청 시간을 반환합니다.

하지만 완주율(completion rate) — 사람들이 실제로 시청한 영상의 비율 — 은 반환하지 않습니다. 실제 계정에서 약 700개의 릴을 측정한 결과, 완주율이 릴의 죽음과 확산을 가르는 기준이었습니다:

조회수는 결과입니다. 완주율은 원인이며, 게시 후 며칠이 아닌 몇 시간 안에 확인할 수 있습니다.

이를 계산하려면 avg_watch_time / duration이 필요합니다. 그런데 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일을 재설정하므로 일찍 갱신해도 손해가 없습니다.

launchd 작업이 조용히 파일을 읽지 못하는 macOS 함정을 포함한 스케줄링 참고 사항은 SETUP.md에 있습니다.

쓰기 전에 .env를 백업하고, 중복 키를 다시 쓰며, 실패 시 알림을 보냅니다.

갱신해도 기존 토큰은 무효화되지 않으므로 여러 머신이 각자 자신의 .env를 독립적으로 갱신할 수 있습니다. 토큰 값은 호스트 간에 동기화할 필요가 없습니다.

구축 과정에서 얻은 것들

실제 시간이 많이 들었던 것들로, 일반화할 수 있는 부분이라 여기에 기록해 둡니다.

sys.exit()는 CLI에서는 괜찮지만 서버에서는 치명적입니다. 첫 번째 버전은 기존 명령줄 스크립트의 함수를 재사용했습니다. 그 함수는 토큰이 거부되면 sys.exit()를 호출했는데, 토큰이 만료된 날 서버 프로세스 전체를 죽였을 것입니다. 이제 도구는 ValueError를 발생시킵니다. SDK는 표준 예외를 모델이 조치할 수 있는 읽기 가능한 결과로 변환하며, 서버는 살아남습니다.

오류는 무엇을 해야 하는지 말해야 합니다. 죽은 토큰은 스택 트레이스가 아닌 재생성 절차를 반환합니다. 모델은 이를 실제로 고칠 수 있는 사람에게 전달할 수 있습니다.

독스트링이 인터페이스입니다. 모델이 도구를 호출할지 여부를 결정하는 기준이므로, 각 도구는 무엇을 반환하는지뿐만 아니라 언제 사용해야 하는지도 명시합니다.

예약 작업은 조용히 실패할 수 있습니다. macOS에서 갱신 스크립트용 launchd 타이머가 Operation not permitted로 실패했는데, TCC가 백그라운드 에이전트가 보호된 디렉터리를 읽는 것을 차단했기 때문입니다. 로드된 것으로 보고되었고 조용히 실행되지 않았을 것입니다. 강제 실행과 로그 확인만이 이를 드러내는 유일한 방법입니다.

.env의 중복 키는 실제 함정입니다. 오래된 중복 키가 로더의 해석 방식에 따라 새로 쓴 토큰을 가릴 수 있으므로, 작성기는 첫 번째 항목이 아닌 모든 항목을 다시 씁니다.

API 이름이 변경되었습니다. mcp.server.mcpserver.MCPServer이며, 이전의 mcp.server.fastmcp.FastMCP 경로는 다른 레거시 모듈과 함께 mcp 2.x에서 제거되었습니다. 온라인의 대부분의 예제는 여전히 이전 import를 보여주며 실행되지 않습니다.

라이선스

MIT