instagram-mcp

원격 MCP 서버로, 각 팀원이 Claude 대화에서 직접 자신의 Instagram 전문 계정에만 Instagram 캐러셀과 단일 이미지를 게시할 수 있도록 합니다. 다른 사람의 계정에는 게시할 수 없습니다.

Bearer 토큰이 사용자를 식별합니다. 사용자는 데이터베이스에서 정확히 하나의 Instagram 계정에 매핑됩니다. 어떤 도구도 Instagram 계정 ID를 매개변수로 사용하지 않으므로, 잘못된 ID를 전달하여 팀원의 계정에 게시하는 것은 구조적으로 불가능합니다.

Meta 앱은 개발 모드로 실행되며 모든 팀원이 Instagram 테스터로 추가됩니다. — Meta 앱 리뷰, OAuth 로그인 흐름, 라이브 전환은 필요하지 않습니다. 이는 의도적인 설계입니다.

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은 24시간 동안 API 게시를 100개로 제한합니다)

• 토큰 상태 확인 (Instagram 연결은 만료되기 훨씬 전에 자동으로 갱신됩니다. 문제가 있는지 알려줍니다)

• 최근 게시물 목록 보기 (항상 귀하의 게시물만)

게시가 중간에 실패하면 Claude에게 동일한 게시를 다시 시도하라고 요청하세요. 서버는 중단된 지점부터 다시 시작하며 중복 게시되지 않습니다.

새 팀원 온보딩 (관리자)

사전 준비 사항 (1인당 한 번):

1. 해당 Instagram 계정은 전문 계정(비즈니스 또는 크리에이터)이어야 합니다.

2. developers.facebook.com에서 Meta 앱을 열고 Instagram → Instagram 로그인을 통한 API 설정으로 이동하여 계정을 Instagram 테스터로 추가합니다. 테스터는 초대를 수락해야 합니다 (Instagram 앱 → 설정 → 웹사이트 권한 → 앱 및 웹사이트 → 테스터 초대).

3. 앱 대시보드에서 계정에 대한 장기 액세스 토큰을 생성합니다 (테스터 계정 옆의 "토큰 생성" 버튼). 토큰을 복사하고 계정의 사용자 ID를 기록합니다.

그런 다음 시드합니다 (자신의 머신에서, 이 리포지토리에서, .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에 대해 토큰을 실시간으로 확인하고, 전달한 ID와 다른 계정에 속한 토큰은 시드를 거부하며, 멤버의 igmcp_ Bearer 토큰을 한 번 출력합니다. 위의 "Claude에 연결하기" 섹션과 함께 안전한 채널을 통해 전송하세요.

누군가를 해지하려면: team_members 테이블의 해당 행에 revoked_at = now()를 설정합니다. 해당 토큰은 즉시 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

주요 결정 사항:

• 전송 방식: @modelcontextprotocol/server v2와 함께 mcp-handler v2 (Vercel의 MCP 어댑터) — Streamable HTTP만 지원합니다. 더 이상 사용되지 않는 HTTP+SSE 전송 방식은 v2에서 상위 호환성 없이 제거되었으며, 이것이 바로 우리가 원하는 것입니다. 수제 전송 방식은 없습니다.

• 호스트: 모든 통신은 https://graph.instagram.com (Instagram 로그인 경로)과 이루어집니다. graph.facebook.com은 Facebook 로그인 경로에 속하며 오해의 소지가 있는 토큰 구문 분석 오류와 함께 실패합니다. 대부분의 튜토리얼이 이것을 잘못 설명합니다.

• 인증: 모든 요청에 Authorization: Bearer <token>이 포함됩니다. 토큰은 해시(SHA-256)되어 조회되고 일정 시간 비교로 재확인됩니다. 알 수 없거나 해지된 토큰은 모든 처리 전에 401을 반환합니다. Instagram 토큰은 Postgres에 AES-256-GCM으로 암호화되어 저장됩니다. Bearer 토큰은 절대 원시 형태로 저장되지 않습니다.

• 멱등성: 멱등성 키(멤버 + 이미지 URL + 캡션)는 Meta 호출 전에 posts에 기록됩니다. 하위 컨테이너 ID는 생성될 때 유지됩니다. 재시도는 FINISHED 하위 항목을 재사용하고 EXPIRED/ERRORED 항목만 다시 생성하며, 동일한 상위 컨테이너 ID를 다시 게시하는 것은 안전합니다(media_publish는 컨테이너당 멱등적입니다). 따라서 반쯤 게시된 캐러셀이 중복될 수 없습니다.

• 토큰 갱신: Vercel Cron이 매일 실행됩니다. 토큰은 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는 일반적인 이름이며 서비스 역할 클라이언트는 전체 테이블 액세스 권한을 가지므로 관련 없는 제품과 스키마를 공유하는 것은 충돌(및 폭발 반경) 위험이 있습니다. 자신의 계정으로 프로젝트를 만든 다음 SQL 편집기 또는 Supabase MCP 커넥터를 통해 supabase/migrations/의 마이그레이션을 적용합니다.

R2 버킷은 R2_PUBLIC_BASE_URL과 일치하는 공개 액세스(사용자 지정 도메인 또는 r2.dev)가 필요합니다.

라이브 승인 테스트

.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은 계정당 롤링 24시간 동안 100개의 게시물로 게시를 제한합니다. get_publishing_limit는 실시간 카운터를 읽습니다.

• 컨테이너는 약 24시간 후에 만료되며 계정당 약 50개의 보류 중인 컨테이너 상한이 있습니다. 이것이 재시도 경로가 새 컨테이너를 생성하는 대신 기존 컨테이너를 재사용하는 또 다른 이유입니다.

• 캐러셀 슬라이드는 동일한 종횡비로 유지하세요. Instagram은 첫 번째 슬라이드에 맞게 모든 것을 자릅니다. JPEG/PNG만 가능하며, 8MB 이하여야 합니다.