Instagram MCP Server

호스팅형 Model Context Protocol(MCP) 서버로, Claude, Cursor, Windsurf 및 기타 모든 MCP 클라이언트에 두 가지 읽기 전용 Instagram 도구를 제공합니다. 핸들로 공개 프로필을 조회하고, 공개 게시물 피드를 구조화된 JSON으로 탐색할 수 있습니다.

계정에 대한 공개 데이터를 읽습니다. 계정으로 활동하지 않으며, 연결할 것이 없고 어떤 흐름에도 사용자의 계정이 관여하지 않습니다.

https://mcp.hasdata.com/api/mcp?apis=instagram

목차

• 필요한 것

• 빠른 시작

• 예시 프롬프트

• 도구

• 오류 및 실패 경로

• 가격, 무료 티어 및 한도

• 도구 선택

• 비교

• FAQ

• HasData 링크

• 개발

• 기여

• 라이선스

Related MCP server: Google Search MCP Server

필요한 것

스트리밍 가능한 HTTP와 사용자 지정 헤더를 지원하는 MCP 클라이언트. 대시보드에서 만드는 HasData API 키(카드 없이 무료로 생성할 수 있고 체험판에 100회 호출 포함). 이것만 있으면 됩니다. 이 서버는 원격 서버이므로 가장 간단한 방법은 컨테이너를 실행할 필요 없이 URL과 헤더를 사용하는 것입니다. stdio 전용 클라이언트는 대신 @hasdata/instagram-mcp(npm) 또는 hasdata-instagram-mcp(PyPI) 런처를 사용할 수 있습니다.

빠른 시작

서버 URL은 모든 클라이언트에서 동일합니다. 저희는 Claude Code와 Claude Desktop에서 직접 실행했습니다. 나머지 블록은 각 클라이언트가 문서화한 원격 서버 형식을 따릅니다.

OAuth를 지원하는 클라이언트는 동일한 URL을 커넥터로 추가하고 구성 파일에 키를 입력하지 않고 로그인할 수 있습니다.

claude mcp add --transport http instagram "https://mcp.hasdata.com/api/mcp?apis=instagram" \
  --header "x-api-key: HASDATA_API_KEY"

Claude Desktop은 구성 파일에서 로컬(stdio) 서버만 로드하므로 stdio 런처를 통해 원격 서버에 연결합니다. @hasdata/instagram-mcp 패키지가 바로 그 런처이며, 키를 환경 변수에서 읽습니다.

claude_desktop_config.json:

{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": ["-y", "@hasdata/instagram-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

Node 대신 Python을 사용하나요? 수동 설치 없이 uvx가 실행하는 PyPI 패키지로 런처를 바꾸면 됩니다:

{
  "mcpServers": {
    "instagram": {
      "command": "uvx",
      "args": ["hasdata-instagram-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

OAuth를 지원하는 클라이언트는 대신 URL을 사용자 지정 커넥터로 추가하고 런처를 건너뛸 수 있습니다.

.cursor/mcp.json:

{
  "mcpServers": {
    "instagram": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=instagram",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "instagram": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=instagram",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "instagram": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=instagram",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}

.vscode/mcp.json:

{
  "servers": {
    "instagram": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=instagram",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

~/.gemini/settings.json:

{
  "mcpServers": {
    "instagram": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=instagram",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

예시 프롬프트

각 예시는 별도로 명시된 횟수가 없으면 한 번의 도구 호출입니다.

@nasa 프로필을 조회해서 팔로워 수, 카테고리, 소개(bio)의 모든 링크를 알려줘.

한 번의 호출, 10크레딧. 공개 계정의 경우 프로필 응답에 이미 최근 게시물 12개가 포함되어 있으므로 최근 활동에 대한 후속 조회는 추가 호출이 필요 없습니다.

@nasa, @natgeo, @bbcearth를 팔로워 수, 게시된 게시물 수, 각각 비즈니스 계정인지 여부 기준으로 비교해 줘.

3회 호출, 30크레딧. 핸들당 한 번씩.

@nasa의 최근 게시물 50개를 탐색하면서 모든 해시태그와 각각의 등장 횟수를 목록으로 작성해 줘.

5회 호출, 50크레딧. 호출당 12개의 게시물이 도착하며, 50개는 5페이지가 필요합니다.

@natgeo의 최근 게시물 12개에 대해 각 캡션에서 좋아요 수, 댓글 수, 언급된 계정을 알려줘.

한 번의 호출, 10크레딧. 참여 횟수와 멘션은 게시물 객체에 파싱된 상태로 제공됩니다.

이것들이 동작하는 데는 두 가지 이유가 있습니다. 해시태그와 멘션은 캡션에서 파싱된 배열로 제공되며, 에이전트는 문장에 정규식을 실행하는 대신 그것들을 집계합니다. 그리고 프로필 조회는 같은 응답에서 최근 피드를 반환합니다. 그렇기 때문에 많은 조사 질문이 단 한 번의 호출로 해결되는 것입니다.

도구

두 가지 도구로, 둘 다 읽기 전용이며 공개 계정 핸들에 키가 지정됩니다. 아래 샘플은 실제 호출에서 일부를 발췌한 것이며, 그 안의 숫자는 계정이 게시함에 따라 변합니다. 형태로 읽으십시오. 각 도구 이름은 엔드포인트 참조 문서에 링크됩니다.

샘플은 전체 응답이 아니라 페이로드입니다. tools/call 결과는 하나의 텍스트 블록을 담고 있으며, 그 텍스트 자체가 url, status, text, json을 포함하는 JSON이고 스크래핑된 데이터는 json 아래에 있습니다. 원시 JSON-RPC 응답에서 경로는 result.content[0].text이며, 이를 파싱한 다음 .json입니다. 채팅 클라이언트는 이를 대신 풀어 주지만, 엔드포인트에 직접 통신하는 코드는 직접 처리해야 합니다.

Instagram 프로필 가져오기

hasdata_instagram_profile_getInstagramProfile

핸들로 하나의 공개 프로필을 가져옵니다.

id, username, fullName, biography, businessCategory, verified, isBusinessAccount, isProfessionalAccount, 카운터 followersCount, followsCount, postsCount, highlightsCount, igtvVideoCount, profilePicUrl과 profilePicUrlHD 둘 다, 그리고 배열 latestPosts, latestIgtvVideos, relatedProfiles을 반환합니다.

핵심 식별 필드와 팔로워·팔로잉 수는 모든 공개 계정에서 반환됩니다. 그 외의 필드는 계정 자체가 노출하는 내용에 따라 달라지므로 선택 필드는 기본값과 함께 읽으십시오.

링크는 서로 다른 두 필드에 있습니다. bioLinks는 소개(bio)의 모든 링크 배열입니다. externalUrls는 복수 이름과 달리 단일 문자열이며 기본 링크를 담고 있고, 배열 버전에는 없는 후행 슬래시가 붙는 경우도 있습니다. 모두 원하면 bioLinks를 읽으십시오.

latestPosts와 latestIgtvVideos는 동일한 필드를 갖지 않습니다. 비디오 항목은 taggedUsers를 추가하며, 여기 게시물 객체는 posts 도구가 포함하는 productType을 생략합니다. 하나의 파서로 두 배열을 모두 처리하는 코드는 추가 키를 선택 사항으로 취급해야 합니다.

{
  "id": "528817151",
  "username": "nasa",
  "fullName": "NASA",
  "biography": "Making the seemingly impossible, possible. ✨",
  "businessCategory": "Government Agencies",
  "bioLinks": [
    "https://www.nasa.gov",
    "https://science.nasa.gov/mission/roman-space-telescope/",
    "http://intern.nasa.gov"
  ],
  "externalUrls": "https://www.nasa.gov/",
  "followersCount": 104397669,
  "followsCount": 92,
  "postsCount": 4887,
  "verified": true,
  "isBusinessAccount": true,
  "latestPosts": [ "…twelve most recent posts, same shape as the posts tool…" ],
  "relatedProfiles": [
    { "id": "…", "username": "…", "fullName": "…", "profilePicUrl": "…" }
  ]
}

relatedProfiles는 Instagram이 해당 계정에 대해 제공하는 자체 추천 목록이며 수십 개 항목에 달합니다. 핸들을 추측하지 않고 경쟁사 집합을 넓힐 수 있는 저비용 방법입니다.

Instagram 게시물 가져오기

hasdata_instagram_posts_getInstagramPosts

한 핸들의 공개 게시물 피드를 페이지별로 가져옵니다.

limit은 정확한 개수가 아니라 대략적인 상한입니다. 게시물 12개는 Instagram 한 페이지이며 단일 호출의 하드 상한이고, limit: 50은 12개를 반환합니다. 상한 이하에서는 개수가 항상 일치하지는 않지만 요청한 숫자에 가깝게 나오며, 얼마나 가까운지는 계정에 따라 다릅니다. @nasa에서 측정했을 때 limit 2는 게시물 4개, 6은 6개, 11은 10개, 13은 12개를 반환했습니다. "대략 이 정도를 넘지 않는다"로 취급하고, 가정하지 말고 배열 길이를 읽으십시오.

응답은 게시물과 함께 계정의 식별 필드를 반복합니다. username, id, fullName, verified 및 두 아바타 URL이 모든 페이지에 포함됩니다. 행에 레이블을 붙일 때 유용하며, 별도로 프로필 호출을 해서 가져오기 전에 알아 두면 좋습니다.

각 게시물은 id, shortcode, caption, type, productType, hashtags, mentions, likesCount, commentsCount, timestamp, url, displayUrl, images, dimensionsWidth, dimensionsHeight, ownerId, ownerUsername을 담고 있습니다.

{
  "username": "nasa",
  "id": "528817151",
  "fullName": "NASA",
  "verified": true,
  "latestPosts": [
    {
      "id": "3967213292204992434",
      "shortcode": "DcOX3hWFiey",
      "caption": "With your powers combined…\n\nThis colorful picture of the cosmos is the product of teamwork between our @NASAHubble, @NASAWebb, and @NASAChandraXray telescopes. […] \n\n#NASA #Universe #Nebula",
      "type": "Image",
      "hashtags": ["#NASA", "#Universe", "#Nebula"],
      "mentions": ["@NASAHubble", "@NASAWebb", "@NASAChandraXray"],
      "likesCount": 78412,
      "commentsCount": 402,
      "timestamp": "2026-08-18T16:02:11.000Z",
      "url": "https://www.instagram.com/p/DcOX3hWFiey/"
    }
  ],
  "pagination": {
    "morePostsAvailable": true,
    "nextPageToken": "3968050822236429248_528817151",
    "hasdataLink": "https://api.hasdata.com/scrape/instagram/posts?handle=nasa&nextPageToken=3968050822236429248_528817151"
  }
}

해시태그와 멘션은 #와 @ 접두사를 유지하므로, 직접 만든 목록과 조인할 때 중요합니다. morePostsAvailable은 페이지를 넘길 때 분기할 플래그이며, hasdataLink는 같은 다음 페이지를 REST URL로 표현한 것으로 에이전트의 호출을 직접 재현하고 싶을 때 유용합니다.

오류 및 실패 경로

도구 호출에서 클라이언트가 HTTP 오류 코드를 보는 경우는 거의 없습니다. MCP 계층은 200으로 응답하고 실패를 결과 내부에 넣으며, isError를 true로 설정하고 이유를 텍스트로 담습니다. 에이전트는 상태 줄이 있을 법한 자리에 메시지를 읽습니다.

잘못된 키는 연결 실패가 아니라 도구 출력으로 드러납니다. 도구 목록 요청은 비어 있지 않은 키를 모두 허용하며, 클라이언트는 핸드셰이크를 마치고 초록색을 표시합니다. 그런 다음 첫 번째 도구 호출이 isError: true와 함께 HasData API error: 401 Unauthorized 텍스트로 돌아옵니다. 그 문자열을 주시하세요. 흐름의 그 이전에는 문제를 보고하는 것이 없기 때문입니다.

키가 누락된 경우가 유일한 실제 HTTP 오류입니다. 인증은 모든 도구보다 먼저 실행되며, 연결 자체가 401로 실패합니다.

스키마를 위반하는 인수는 요청이 되기 전에 거부됩니다. 서버는 필드 이름을 명시한 isError: true 및 MCP error -32602: Input validation error 텍스트로 응답합니다. 아무것도 가져오지 않으며 요금도 부과되지 않습니다.

확인할 수 없는 핸들은 빈 데이터가 아니라 명확한 오류입니다. isError: true와 함께 HasData API error: 400 Bad Request를 반환하고 requestMetadata.status는 error로 설정됩니다. 실패가 모호하지 않기 때문에 이것은 좋은 경우입니다. 배열 길이보다 플래그를 테스트하십시오.

데이터가 공개되지 않은 계정은 게시물 피드를 반환하지 않습니다. 도구는 공개 계정을 대상으로 하며, 공개되지 않은 계정에는 읽을 것이 없습니다. latestPosts가 없으면 빈 피드가 아니라 범위 밖으로 처리하십시오.

데이터를 담은 결과에는 지원 시 인용할 만한 requestMetadata.id와 함께, 해당 호출의 저장된 산출물에 대한 html 및 json 링크가 포함됩니다.

가격, 무료 티어 및 한도

모든 Instagram 도구는 성공적인 호출당 10크레딧이 듭니다. 응답 크기는 가격을 바꾸지 않습니다. 게시물 12개가 첨부된 프로필도 게시물이 없는 프로필과 같은 비용입니다.

무료 체험은 카드 없이 30일간 1,000크레딧, 즉 Instagram 호출 100회입니다. 이후 활성 계정은 잔액이 100 미만으로 떨어질 때마다 매일 100크레딧이 충전되므로, 낮은 볼륨의 에이전트는 무료 등급에서 무기한 실해될 수 있습니다.

유료 요금제는 월 49달러부터이며, 200,000크레딧, 즉 20,000회 호출이 포합됩니다. 단가는 볼륨이 커질수록 낮아져서, 엔트리 요금제의 1,000회 호출당 2.45달러에서 Business 0.99달러, Growth 0.83달러, 그리고 가장 큰 고용량 요금제의 0.75달러까지입니다.

요금제는 동시성도 결정합니다. 무료 체험은 한 번에 1개 요청, Startup은 15개, Business는 30개, Growth는 50개를 허용하며, 고용량 요금제는 200~1,500개입니다. 무인으로 실해되는 모든 작업에서는 오버플로(overflow) 상황을 방어적으로 처하세요. 여러 핸들에 걸쳐 작업을 펼치는 에이전트는 여러분보다 먼저 상한에 도달하기 때문입니다.

페이징은 매번 호출 1회를 소모합니다. 두 계정의 게시물 백 개를 는 프롬프트는 18회 호출과 180크레딧이 듭니다. 무료 체험은 깊은 피드 크롤링보다 프로필 비교에서 더 오래갑니다.

도구 선택

?apis=instagram은 정확히 이 두 도구를 노출합니다. 이 파라미터는 목록을 받으며, ?apis=instagram,tiktok,youtube는 에이전트에 소셜 플랫폼 세 개를 한 번에 제공합니다. 파라미터를 빼면 HasData가 노출하는 모든 것, 현제 57개 도구를 얻습니다.

좂은 목록이 보통 더 나은 기본값입니다. 두 도구 중에서 선택하는 모델이 57개 중에서 선택하는 모델보다 더 자주 올바르게 고르며, 도구 설명 자체도 매 마다 컨텐스트를 소모합니다.

목록을 넢히는 일바적인 이유는 크로스 플랫폼 비교입니다. Instagram 핸들과 TikTok 핸들에 같은 질문을 하면, 둘 다 노출되어 있는 한 하니의 프롬프트로 처됩니다.

다은 서버와의 비고

거의 모든 Instagram MCP 서버는 이 서버와 다은 일을 하며, 그 덕분에 선택이 매우 명확합니다.

인기 있는 서버들은 계정을 운용합니다. 어 것들은 Instagram Graph API를 감싸서 게시물을 게시하고, 댓글을 읽고, 여러분이 관하는 계정을 관합니다. 다은 것들은 직접 메시지(DM)를 처합니다. 참여도 분석 서버들은 각자의 설적 지침에 따라 env 블록에서 INSTAGRAM_USERNAME과 INSTAGRAM_PASSWORD를 요구합니다. 여러분으로 로그인하여 여러분으로 브라우징하기 때문입니다. 여러분이 제어하는 계정을 운용하는 일이라면 그런 서버들이 모두 올바른 도구입니다.

이 서버는 누구로도 로그인하지 않으며, 이것은 다은 작업입니다. 이 서버가 답하는 모든 질문은 여러분이 소유하지 않은 핸들에 관한 것이며, 어 핸들이든 호출은 동일합니다.

두 행이 결정합니다. 게시, 댓글, 답변이 필요하다면 이 서버는 전혀 도움이 되지 않습니다. 관게가 없는 백 개의 핸들에 걸쳐 동일한 필드가 필요하다면, 여러분의 자격 증명을 기반으로 구축된 서버도 도움이 되지 않습니다.

결정 기준은 완성도가 아니라 범위입니다. 여러분의 로그인을 기반으로 구축된 서버는 출략이 아무리 좋아도 여러분이 관하는 계정에만 접근할 수 있습니다. 이 서버는 모든 공개 핸들에 대해 동일한 질문에 답하며, 필드는 파싱된 배열로 돌아와서 집계에 비용이 들지 않습니다.

이 서버가 하지 않는 일. 댓글 없음, 스토리 없음, 피드가 보도하는 것 이상의 릴스 없음, 직접 메시지 없음, 해시태그 또는 위티 검색 없음, 그리고 쓰기 작업이 전혀 없음. 두 가것을 잘 읽습니다.

FAQ

Instagram MCP 서버란 무엇인가요?

Instagram 데이터를 AI 클라이언트가 호출할 수 있는 도구로 노출하는 서버입니다. 클라이언트는 Model Context Protocol을 통해 도구 호출을 보내고, 서버는 데이터를 가져와 구조화된 JSON을 반환하며, 모델은 그 결과를 사용하고 HTML 페이지는 결코 보지 않습니다. 이 서버는 두 개의 읽기 전용 도구를 노출하며 원격으로 실해됩니다. 클라이언트는 URL에 연결할 뿐 로컬 프로세스를 시각하지 않습니다.

공식 Instagram MCP 서버가 있나요?

Meta는 범용 서버를 공개하지 않습니다. Meta 광고용 공식 MCP는 있으며, 광고 계정과 캠페인을 다루고 프로필 및 게시물 데이터는 다루지 않습니다. 이 분야의 다은 모든 것은 다은 누군가가 만든 것입니다.

어떤 데이터가 범위에 포함되나요?

공개 계정의 핸들별 공개 프로필 필드와 공개 게시물 피드입니다. 비공개 계정도 헤더, 팔로워 및 팔로잉 수, private: true 플래그는 반환하지만, 읽을 공개 피드가 없으므로 소개(biography)와 게시물은 반환하지 않습니다. 결과 사용 방식에 대한 책임은 여러분에게 있으며, Instagram 약관 및 여러분에게 적용되는 법률 준수도 포함됩니다.

무언가를 호스팅하거나 실행해야 하나요?

아니요. 이는 streamable HTTP 기반의 원격 MCP 서버입니다. 설치할 것도, Python 환경도, 재시작할 프로세스도 없습니다.

데이터는 실시간인가요, 캐시된 것인가요?

실시간입니다. 각 호출은 요청 시점에 가져오며 고유한 requestMetadata.id를 지닙니다. 동일한 두 호출은 저장된 복사본의 재생이 아니라 별개의 두 가져오기입니다. 팔로워 수나 좋아요 수 같은 카운터는 계정을 추적하며 계정이 변하는 대로 변합니다.

게시물은 몇 개나 얻을 수 있나요?

호출당 12개, 즉 Instagram 페이지 하나이며, 추가 페이지는 pagination.nextPageToken으로 가져옵니다. 공개 계정의 경우 프로필 조회에 동일한 12개가 추가 비용 없이 포함되므로, 짧은 피드 질문은 게시물 호출이 아예 필요 없는 경우가 많습니다.

Instagram이 마크업을 변경하면 어떻게 되나요?

여러분 쪽에서는 아무 일도 일어나지 않습니다. 저희가 변경 사항을 추적하고 응답 스키마를 안정적으로 유지하며, 필드 이름과 유형도 그대로 유지됩니다. 값이 없는 필드는 null로 존재하는 대신 항목에서 아예 빠져 있습니다. 그래서 선택적 필드는 기본값과 함께 읽어야 합니다.

하나의 서버를 여러 플랫폼에 사용할 수 있나요?

네. apis 파라미터는 목록을 받으며, ?apis=instagram,tiktok,youtube는 에이전트에 세 개의 플랫폼을 한 번에 제공합니다.

어떤 클라이언트가 작동하나요?

사용자 지적 헤더와 함께 streamable HTTP를 지원하는 모든 MCP 클라이언트입니다. 위의 구성은 테스트된 것입니다. OAuth를 지원하는 클라이언트는 대신 URL을 커넥터로 추가할 수 있습니다.

HasData 링크

개발

이 저장소는 원격 서버에 대한 구성과 문서입니다. 빌드 단계도, 컨테이너화할 것도 없습니다.

다만 계약 테스트는 포함되어 있습니다. README는 특정 파라미터를 가진 두 개의 도구를 약속하며, 업스트림 도구 목록은 여기에 커밋 없이도 변경될 수 있습니다. 그렇게 되면 이 파일은 여러분에게 조용히 거짓말을 하게 됩니다. 테스트는 그 약속을 검증하며 CI에서 매주, 그리고 모든 푸시 때마다 실행됩니다.

HASDATA_API_KEY=your_key_here npm test

PowerShell에서:

$env:HASDATA_API_KEY = "your_key_here"; npm test

마지막 검사는 실제 호출을 하여 10크레딧이 듭니다. 이는 올바른 이유로 실패할 수 있는 카나리(canary)의 대가입니다. 도구 목록 나열은 비어 있지 않은 어떤 키로도 성공하며, 도구 목록만 나열하는 테스트는 폐기된 키로도 계속 통과합니다.

기여하기

도구 표와 응답 샘플에 대한 수정이 가장 유용한 기여입니다. 그것들이 가장 많이 변하는 부분이기 때문입니다. 여러분이 만든 호출과 받은 응답을 포함해 주세요. 포크에서 온 풀 리퀘스트는 키 없이 테스트 스위트를 실해하며, 실시간 검사는 빨간불이 되는 대신 건너니다.

라이선스

MIT. LICENSE를 참조하세요.