Instagram MCP Server

Instagram의 Graph API와 원활하게 통합되는 Model Context Protocol(MCP) 서버로, AI 애플리케이션이 Instagram 비즈니스 계정과 프로그래밍 방식으로 상호작용할 수 있게 해줍니다.

기능

🔧 도구(모델 제어)

• 프로필 정보 가져오기: Instagram 비즈니스 프로필 세부 정보 검색

• 미디어 게시물 가져오기: Instagram 계정의 최근 게시물 가져오기

• 미디어 인사이트 가져오기: 특정 게시물의 참여 지표 검색

• 미디어 게시: 이미지/비디오를 Instagram에 업로드 및 게시

• 계정 페이지 목록: 계정에 연결된 Facebook 페이지 나열

• 대화 목록: Instagram DM 대화 나열(고급 액세스 필요)

• 대화 메시지 가져오기: 특정 대화의 메시지 읽기(고급 액세스 필요)

• DM 보내기: Instagram 다이렉트 메시지에 답장(고급 액세스 필요)

📊 리소스(애플리케이션 제어)

• 프로필 데이터: 팔로워 수, 소개 등 프로필 정보에 대한 액세스

• 미디어 피드: 참여 지표가 포함된 최근 게시물

• 인사이트 데이터: 게시물 및 계정 성과에 대한 상세 분석

💬 프롬프트(사용자 제어)

• 참여도 분석: 게시물 성과 분석을 위한 사전 구축 프롬프트

• 콘텐츠 전략: 콘텐츠 추천 생성을 위한 템플릿

• 해시태그 분석: 해시태그 성과 평가를 위한 프롬프트

Related MCP server: instagram-mcp

사전 요구 사항

1. Instagram 비즈니스 계정: Facebook 페이지에 연결되어 있어야 함

2. Facebook 개발자 계정: API 액세스에 필요

3. 액세스 토큰: 적절한 권한이 있는 장기 액세스 토큰

4. Python 3.10 이상: MCP 서버 실행용(MCP 종속성에 필요)

필수 Instagram API 권한

표준 액세스(즉시 사용 가능):

• instagram_basic

• instagram_content_publish

• instagram_manage_insights

• instagram_manage_comments

• pages_show_list

• pages_read_engagement

• pages_manage_metadata

• pages_read_user_content

• business_management

고급 액세스(Meta 앱 검토 필요):

• instagram_manage_messages - 다이렉트 메시징 기능에 필요

⚠️ Instagram DM 기능: Instagram 다이렉트 메시지 읽기 및 보내기는 Meta의 고급 액세스 승인이 필요합니다. 앱 검토 프로세스는 INSTAGRAM_DM_SETUP.md를 참조하세요.

🔑 Instagram API 자격 증명 얻는 방법

📖 빠른 시작: 5분 설정 가이드는 AUTHENTICATION_GUIDE.md를 참조하세요!

이 섹션에서는 Instagram MCP 서버에 필요한 자격 증명을 얻는 단계별 가이드를 제공합니다.

1단계: Instagram 비즈니스 계정 설정

1. 비즈니스 계정으로 전환(아직 아닌 경우):

   • Instagram 앱 열기 → 설정 → 계정 → 전문 계정으로 전환

   • "비즈니스" 선택 → 카테고리 선택 → 설정 완료

2. Facebook 페이지에 연결:

   • Instagram 설정 → 계정 → 연결된 계정 → Facebook으로 이동

   • 기존 Facebook 페이지에 연결하거나 새 페이지 생성

   • 중요: Facebook 페이지는 본인이 소유해야 합니다.

2단계: Facebook 앱 만들기

1. Facebook 개발자 사이트로 이동:

   • developers.facebook.com 방문

   • Facebook 계정으로 로그인

2. 새 앱 만들기:

   • "앱 만들기" 클릭 → "비즈니스" 선택 → "다음" 클릭

   • 앱 세부 정보 입력:

     • 앱 이름: 설명적인 이름 선택(예: "My Instagram MCP Server")

     • 앱 연락처 이메일: 본인의 이메일 주소

   • "앱 만들기" 클릭

3. Instagram Basic Display 제품 추가:

   • 앱 대시보드에서 "제품 추가" 클릭

   • "Instagram Basic Display" 찾기 → "설정" 클릭

4. Instagram Basic Display 구성:

   • Instagram Basic Display → Basic Display로 이동

   • Instagram 앱 섹션에서 "새 앱 만들기" 클릭

   • 약관에 동의하고 앱 생성

3단계: 앱 자격 증명 가져오기

1. 앱 ID 및 시크릿 가져오기:

   • Facebook 앱 대시보드에서 설정 → 기본 정보로 이동

   • 앱 ID 및 앱 시크릿 복사

   • 중요: 앱 시크릿을 안전하게 보관하고 공개적으로 공유하지 마세요.

4단계: Instagram 비즈니스 API 액세스 설정

1. Instagram Graph API 제품 추가:

   • 앱 대시보드에서 "제품 추가" 클릭

   • "Instagram Graph API" 찾기 → "설정" 클릭

2. 권한 구성:

   • Instagram Graph API → 권한으로 이동

   • 다음 권한 요청:

     • instagram_basic

     • instagram_content_publish

     • instagram_manage_insights

     • pages_show_list

     • pages_read_engagement

5단계: 액세스 토큰 생성

옵션 A: Graph API 탐색기 사용(테스트에 권장)

1. Graph API 탐색기로 이동:

   • developers.facebook.com/tools/explorer 방문

2. 탐색기 구성:

   • 드롭다운에서 앱 선택

   • "액세스 토큰 생성" 클릭

   • 메시지가 표시되면 필요한 권한 선택

3. 페이지 액세스 토큰 가져오기:

   • 탐색기에서 GET 요청: /me/accounts

   • 응답에서 Facebook 페이지 찾기

   • 페이지의 access_token 복사

4. Instagram 비즈니스 계정 ID 가져오기:

   • 페이지 액세스 토큰을 사용하여 GET 요청: /{page-id}?fields=instagram_business_account

   • 응답에서 Instagram 비즈니스 계정 ID 복사

옵션 B: Facebook 로그인 흐름 사용(프로덕션에 권장)

1. Facebook 로그인 설정:

   • 앱 대시보드에서 "Facebook 로그인" 제품 추가

   • 유효한 OAuth 리디렉션 URI 구성

2. OAuth 흐름 구현:

   # Example OAuth URL
   oauth_url = f"https://www.facebook.com/v19.0/dialog/oauth?client_id={app_id}&redirect_uri={redirect_uri}&scope=pages_show_list,instagram_basic,instagram_content_publish,instagram_manage_insights"

3. 코드를 토큰으로 교환:

   # Exchange authorization code for access token
   token_url = f"https://graph.facebook.com/v19.0/oauth/access_token?client_id={app_id}&redirect_uri={redirect_uri}&client_secret={app_secret}&code={auth_code}"

6단계: 장기 액세스 토큰 가져오기

단기 토큰은 1시간 후 만료됩니다. 장기 토큰(60일)으로 변환:

curl -X GET "https://graph.facebook.com/v19.0/oauth/access_token?grant_type=fb_exchange_token&client_id={app_id}&client_secret={app_secret}&fb_exchange_token={short_lived_token}"

7단계: 환경 변수 설정

프로젝트 루트에 .env 파일 생성:

# Facebook App Credentials
FACEBOOK_APP_ID=your_app_id_here
FACEBOOK_APP_SECRET=your_app_secret_here

# Instagram Access Token (long-lived)
INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token_here

# Instagram Business Account ID
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id_here

# Optional: API Configuration
INSTAGRAM_API_VERSION=v19.0
RATE_LIMIT_REQUESTS_PER_HOUR=200
CACHE_ENABLED=true
LOG_LEVEL=INFO

8단계: 설정 테스트

검증 스크립트를 실행하여 자격 증명을 테스트:

python scripts/setup.py

또는 수동으로 테스트:

import os
import requests

# Test access token
access_token = os.getenv('INSTAGRAM_ACCESS_TOKEN')
response = requests.get(f'https://graph.facebook.com/v19.0/me?access_token={access_token}')
print(response.json())

🚨 중요한 보안 참고 사항

1. 자격 증명을 버전 관리에 커밋하지 마세요.

2. 환경 변수 또는 안전한 비밀 관리 사용

3. 액세스 토큰을 정기적으로 교체

4. 토큰 만료 날짜 모니터링

5. 프로덕션에서 HTTPS만 사용

6. 만료된 토큰에 대한 적절한 오류 처리 구현

🔄 토큰 갱신 전략

장기 토큰은 60일 후 만료됩니다. 자동 갱신 구현:

# Check token validity
def check_token_validity(access_token):
    url = f"https://graph.facebook.com/v19.0/me?access_token={access_token}"
    response = requests.get(url)
    return response.status_code == 200

# Refresh token before expiration
def refresh_long_lived_token(access_token, app_id, app_secret):
    url = f"https://graph.facebook.com/v19.0/oauth/access_token"
    params = {
        'grant_type': 'fb_exchange_token',
        'client_id': app_id,
        'client_secret': app_secret,
        'fb_exchange_token': access_token
    }
    response = requests.get(url, params=params)
    return response.json().get('access_token')

📋 일반적인 문제 해결

오류: "Invalid OAuth access token"

• 토큰이 만료되었는지 확인

• 토큰에 필요한 권한이 있는지 확인

• Instagram 계정이 Facebook 페이지에 연결되어 있는지 확인

오류: "Instagram account not found"

• Instagram 비즈니스 계정 ID가 올바른지 확인

• Instagram 계정이 Facebook 페이지에 제대로 연결되어 있는지 확인

• 계정이 개인 계정이 아닌 비즈니스 계정인지 확인

오류: "Insufficient permissions"

• Facebook 앱에서 필요한 권한 검토

• 올바른 범위로 액세스 토큰 재생성

• 앱이 개발 모드인지 라이브 모드인지 확인

속도 제한 문제

• 지수 백오프 구현

• 가능한 경우 응답 캐시

• API 응답의 속도 제한 헤더 모니터링

설치

1. 저장소 복제:

git clone <repository-url>
cd ig-mcp

2. 종속성 설치:

pip install -r requirements.txt

3. 환경 변수 설정:

cp .env.example .env
# Edit .env with your Instagram API credentials

4. MCP 서버 구성:

# Edit config.json with your specific settings

구성

환경 변수(.env)

INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token
FACEBOOK_APP_ID=your_facebook_app_id
FACEBOOK_APP_SECRET=your_facebook_app_secret
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id

MCP 클라이언트 구성

MCP 클라이언트 구성(예: Claude Desktop)에 추가:

{
  "mcpServers": {
    "instagram": {
      "command": "python",
      "args": ["/path/to/ig-mcp/src/instagram_mcp_server.py"],
      "env": {
        "INSTAGRAM_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

사용 예시

Claude Desktop에서 사용

1. 프로필 정보 가져오기:

Can you get my Instagram profile information?

2. 최근 게시물 분석:

Show me my last 5 Instagram posts and their engagement metrics

3. 콘텐츠 게시:

Upload this image to my Instagram account with the caption "Beautiful sunset! #photography #nature"

Python MCP 클라이언트에서 사용

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to the Instagram MCP server
server_params = StdioServerParameters(
    command="python",
    args=["src/instagram_mcp_server.py"]
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # Get profile information
        result = await session.call_tool("get_profile_info", {})
        print(result)

다루는 API 엔드포인트

프로필 관리

• 비즈니스 프로필 정보 가져오기

• 프로필 세부 정보 업데이트(향후 기능)

미디어 관리

• 최근 게시물 가져오기

• 특정 미디어 세부 정보 가져오기

• 새 콘텐츠 업로드 및 게시

• 미디어 삭제(향후 기능)

분석 및 인사이트

• 게시물 참여 지표(좋아요, 댓글, 공유)

• 계정 인사이트(도달, 노출)

• 해시태그 성과 분석

계정 관리

• 연결된 Facebook 페이지 나열

• 비즈니스 계정 간 전환

속도 제한 및 모범 사례

서버는 Instagram API 제한을 준수하기 위해 지능형 속도 제한을 구현합니다:

• 프로필 요청: 시간당 200회

• 미디어 요청: 시간당 200회

• 게시: 하루 25개

• 인사이트: 시간당 200회

모범 사례

1. 자주 액세스하는 데이터 캐시

2. 가능한 경우 배치 요청 사용

3. 재시도에 지수 백오프 구현

4. 속도 제한 헤더 모니터링

오류 처리

서버는 일반적인 시나리오에 대한 포괄적인 오류 처리를 제공합니다:

• 인증 오류: 잘못되었거나 만료된 토큰

• 권한 오류: 필요한 권한 누락

• 속도 제한: 백오프를 사용한 자동 재시도

• 네트워크 오류: 연결 시간 초과 및 재시도

• API 오류: Instagram 특정 오류 응답

보안 고려 사항

1. 토큰 보안: 액세스 토큰을 안전하게 저장

2. 환경 변수: 토큰을 버전 관리에 커밋하지 마세요.

3. HTTPS 전용: 모든 API 호출은 HTTPS 사용

4. 토큰 갱신: 자동 토큰 갱신 구현

5. 감사 로깅: 모든 API 상호작용 기록

개발

프로젝트 구조

ig-mcp/
├── src/
│   ├── instagram_mcp_server.py    # Main MCP server
│   ├── instagram_client.py        # Instagram API client
│   ├── models/                    # Data models
│   ├── tools/                     # MCP tools implementation
│   ├── resources/                 # MCP resources implementation
│   └── prompts/                   # MCP prompts implementation
├── tests/                         # Unit and integration tests
├── config/                        # Configuration files
├── requirements.txt               # Python dependencies
├── .env.example                   # Environment variables template
└── README.md                      # This file

테스트 실행

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=src/

# Run specific test file
python -m pytest tests/test_instagram_client.py

기여

1. 저장소 포크

2. 기능 브랜치 생성(git checkout -b feature/amazing-feature)

3. 변경 사항 커밋(git commit -m 'Add amazing feature')

4. 브랜치에 푸시(git push origin feature/amazing-feature)

5. 풀 리퀘스트 열기

문제 해결

일반적인 문제

1. "Invalid Access Token"

   • 토큰이 만료되지 않았는지 확인

   • 토큰 권한 확인

   • 장기 토큰 재생성

2. "Rate Limit Exceeded"

   • 속도 제한 재설정 대기

   • 요청 큐 구현

   • 배치 요청 사용

3. "Permission Denied"

   • Instagram 비즈니스 계정 설정 확인

   • Facebook 페이지 연결 확인

   • API 권한 검토

디버그 모드

다음을 설정하여 디버그 로깅 활성화:

LOG_LEVEL=DEBUG

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

지원

• 📧 이메일: support@example.com

• 🐛 이슈: GitHub Issues

• 📖 문서: Wiki

감사의 말

• Model Context Protocol by Anthropic

• Instagram Graph API by Meta

• FastMCP for rapid MCP development