HasData Instagram MCP Server

Servidor MCP do Instagram

Um servidor de Model Context Protocol (MCP) hospedado que oferece ao Claude, Cursor, Windsurf e qualquer outro cliente MCP duas ferramentas somente leitura do Instagram. Consulte um perfil público pelo identificador e percorra o feed público de postagens, como JSON estruturado.

Ele lê dados públicos sobre contas. Não atua como uma conta. Não há nada para conectar e nenhuma conta sua envolvida em nenhum ponto do fluxo.

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

Conteúdo

• O que você precisa
• Início rápido
• Exemplos de prompts
• Ferramentas
• Erros e caminhos de falha
• Preços, plano gratuito e limites
• Seleção de ferramentas
• Comparação
• Perguntas frequentes
• Links do HasData
• Desenvolvimento
• Contribuição
• Licença

O que você precisa

Um cliente MCP que fale HTTP transmissível com cabeçalhos personalizados. Uma chave de API do HasData do painel, gratuita para criar sem cartão, e o teste cobre 100 chamadas. Nada mais. Este é um servidor remoto, então o caminho mais simples é uma URL e um cabeçalho, sem contêiner para executar. Um cliente somente stdio pode usar o inicializador @hasdata/instagram-mcp (npm) ou hasdata-instagram-mcp (PyPI).

Início rápido

A URL do servidor é a mesma para todos os clientes. Nós a executamos na prática no Claude Code e no Claude Desktop. Os outros blocos seguem o formato documentado de cada cliente para um servidor remoto.

Clientes com suporte a OAuth podem adicionar a mesma URL como conector e entrar sem colocar uma chave em um arquivo de configuração.

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

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

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

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

{
  "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
    }
  }
}

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

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

Exemplos de prompts

Cada um destes é uma chamada de ferramenta, a menos que a contagem indique o contrário.

Consulte o perfil de @nasa e me diga o número de seguidores, a categoria e todos os links na biografia.

Uma chamada, 10 créditos. Para uma conta pública, a resposta do perfil já traz as doze postagens mais recentes, então uma pergunta de acompanhamento sobre atividade recente não precisa de uma segunda chamada.

Compare @nasa, @natgeo e @bbcearth em seguidores, postagens publicadas e se cada uma é uma conta comercial.

Três chamadas, 30 créditos. Uma por identificador.

Percorra as últimas cinquenta postagens de @nasa e liste cada hashtag com a frequência com que aparece.

Cinco chamadas, 50 créditos. Doze postagens chegam por chamada, e cinquenta exigem cinco páginas.

Para as últimas doze postagens de @natgeo, me dê curtidas, comentários e as contas mencionadas em cada legenda.

Uma chamada, 10 créditos. Contagens de engajamento e menções vêm analisadas nos objetos de postagem.

Duas coisas fazem isso funcionar. Hashtags e menções chegam como matrizes extraídas da legenda, e um agente as conta em vez de executar uma regex sobre o texto. E uma consulta de perfil retorna o feed recente na mesma resposta. É por isso que tantas perguntas de pesquisa se resolvem em uma única chamada.

Ferramentas

Duas ferramentas, ambas somente leitura, ambas baseadas em um identificador de conta pública. As amostras abaixo são reduzidas de chamadas reais, e os números nelas mudam conforme as contas postam. Leia-as como formatos. Cada nome de ferramenta vincula à referência do endpoint.

As amostras são o payload, não a resposta inteira. Um resultado tools/call carrega um bloco de texto, e esse texto é em si JSON contendo url, status, text e json, com os dados extraídos sob json. De uma resposta JSON-RPC bruta, o caminho é result.content[0].text, analisado, depois .json. Um cliente de chat desembrulha isso para você, e código que fala diretamente com o endpoint não.

Obter um perfil do Instagram

hasdata_instagram_profile_getInstagramProfile

Um perfil público por identificador.

Retorna id, username, fullName, biography, businessCategory, verified, isBusinessAccount e isProfessionalAccount, os contadores followersCount, followsCount, postsCount, highlightsCount e igtvVideoCount, tanto profilePicUrl quanto profilePicUrlHD, e as matrizes latestPosts, latestIgtvVideos e relatedProfiles.

Os campos principais de identidade e os contadores de seguidores e seguindo voltam para toda conta pública. Os campos além disso dependem do que a própria conta expõe, então leia os opcionais com um padrão.

Os links vivem em dois campos que não são a mesma coisa. bioLinks é a matriz de todos os links na biografia. externalUrls é uma única string apesar do nome no plural, e contém o link principal, às vezes com uma barra final que a versão em matriz não tem. Leia bioLinks quando quiser todos.

latestPosts e latestIgtvVideos não carregam campos idênticos. Entradas de vídeo adicionam taggedUsers, e os objetos de postagem aqui omitem o productType que a ferramenta de postagens inclui. Código que percorre ambas as matrizes com um único analisador precisa tratar as chaves extras como opcionais.

{
  "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 é a própria lista de sugestões do Instagram para a conta e chega a algumas dezenas de entradas. É uma maneira barata de ampliar um conjunto de concorrentes sem adivinhar identificadores.

Obter postagens do Instagram

hasdata_instagram_posts_getInstagramPosts

O feed público de postagens de um identificador, página por página.

limit é um teto aproximado, não uma contagem exata. Doze postagens é uma página do Instagram e o teto rígido para uma única chamada, e limit: 50 retorna doze. Abaixo do teto, a contagem fica perto do número solicitado sem sempre corresponder, e o quão perto depende da conta. Medido em @nasa, um limite de 2 retornou 4 postagens, 6 retornou 6, 11 retornou 10 e 13 retornou 12. Trate como "não mais que aproximadamente isso" e leia o comprimento da matriz em vez de assumir.

A resposta repete os campos de identidade da conta junto com as postagens. username, id, fullName, verified e ambas as URLs de avatar chegam em todas as páginas. Útil para rotular linhas, e vale saber antes de fazer uma chamada separada de perfil para obtê-los.

Cada postagem carrega id, shortcode, caption, type, productType, hashtags, mentions, likesCount, commentsCount, timestamp, url, displayUrl, images, dimensionsWidth, dimensionsHeight, ownerId e 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"
  }
}

Hashtags e menções mantêm seus prefixos # e @, o que importa se você estiver juntando-os a uma lista que construiu. morePostsAvailable é o sinalizador para ramificar ao paginar, e hasdataLink é a mesma próxima página expressa como URL REST, útil quando você quer reproduzir a chamada de um agente manualmente.

Erros e caminhos de falha

Seu cliente quase nunca vê um código de erro HTTP de uma chamada de ferramenta. A camada MCP responde 200 e coloca a falha dentro do resultado, com isError definido como true e o motivo como texto. O agente lê uma mensagem onde você poderia esperar uma linha de status.

Uma chave errada aparece como saída de ferramenta, não como conexão falha. Listar ferramentas aceita qualquer chave não vazia, e o cliente completa o handshake e mostra verde. A primeira chamada de ferramenta então volta com isError: true e o texto HasData API error: 401 Unauthorized. Fique atento a essa string, porque nada antes no fluxo relata o problema.

Uma chave ausente é o único erro HTTP real. A autorização roda antes de qualquer ferramenta, e a própria conexão falha com 401.

Um argumento que quebra o esquema é rejeitado antes de virar uma solicitação. O servidor responde com isError: true e o texto MCP error -32602: Input validation error, nomeando o campo. Nada é buscado e nada é cobrado.

Um identificador que não resolve é um erro limpo, não dados vazios. Retorna isError: true com HasData API error: 400 Bad Request e requestMetadata.status definidos como error. Este é o bom caso, porque a falha é inequívoca. Teste o sinalizador em vez do comprimento da matriz.

Uma conta cujos dados não são públicos não retorna feed de postagens. As ferramentas cobrem contas públicas, e não há nada para ler em uma que não é. Trate um latestPosts ausente como fora do escopo e não como um feed vazio.

Resultados que carregam dados também carregam um requestMetadata.id que vale citar no suporte, além de links html e json para o artefato armazenado daquela chamada exata.

Preços, plano gratuito e limites

Cada ferramenta do Instagram custa 10 créditos por chamada bem-sucedida. O tamanho da resposta não muda o preço. Um perfil com doze postagens anexadas custa o mesmo que um sem nenhuma.

O teste gratuito é 1.000 créditos em 30 dias sem cartão, ou 100 chamadas do Instagram. Depois disso, uma conta ativa continua recebendo 100 créditos por dia sempre que o saldo cair abaixo de 100, então um agente de baixo volume roda no plano gratuito indefinidamente.

Planos pagos começam em US$ 49 por mês para 200.000 créditos, ou 20.000 chamadas. O preço unitário cai com o volume, de US$ 2,45 por 1.000 chamadas no plano inicial para US$ 0,99 no Business, US$ 0,83 no Growth e US$ 0,75 nos maiores planos de alto volume.

Seu plano também define concorrência. O teste gratuito permite 1 solicitação por vez, Startup 15, Business 30, Growth 50, e os planos de alto volume vão de 200 a 1.500. Trate o caso de estouro defensivamente em qualquer coisa não supervisionada, porque um agente que se espalha por identificadores atingirá o teto antes de você.

Paginar custa uma chamada a cada vez. Um prompt que percorre cem postagens em duas contas é dezoito chamadas e 180 créditos. O teste vai mais longe em comparações de perfil do que em rastreamentos profundos de feed.

Seleção de ferramentas

?apis=instagram expõe exatamente essas duas ferramentas. O parâmetro aceita uma lista, e ?apis=instagram,tiktok,youtube dá ao seu agente três plataformas sociais de uma vez. Remova o parâmetro e você obtém tudo o que a HasData expõe, que atualmente são 57 ferramentas.

Uma lista restrita geralmente é o padrão melhor. Um modelo escolhendo entre duas ferramentas acerta com mais frequência do que um que escolhe entre cinquenta e sete, e as próprias descrições das ferramentas custam contexto a cada turno.

A comparação entre plataformas é o motivo usual para ampliar a lista. Faça a mesma pergunta para um perfil do Instagram e para um perfil do TikTok e será um único prompt, desde que ambos estejam expostos.

Como ele se compara

Quase todo servidor MCP do Instagram faz algo diferente deste, e isso torna a escolha excepcionalmente clara.

Os populares operam uma conta. Alguns envolvem a Graph API do Instagram para publicar posts, ler comentários e gerenciar as contas que você administra. Outros lidam com mensagens diretas. Os servidores de análise de engajamento pedem INSTAGRAM_USERNAME e INSTAGRAM_PASSWORD em um bloco de ambiente, conforme suas próprias instruções de configuração, porque eles fazem login e navegam como você. Todos esses são a ferramenta certa quando o trabalho é operar uma conta que você controla.

Este servidor nunca faz login como ninguém, o que é um trabalho diferente. Cada pergunta que ele responde é sobre um perfil que você não possui, e a chamada é idêntica, independentemente de qual perfil seja.

Duas linhas decidem isso. Se você precisa publicar, comentar ou responder, este servidor não pode ajudar em nada. Se você precisa dos mesmos campos em cem perfis com os quais não tem relação, um servidor construído em torno das suas próprias credenciais também não pode ajudar.

O eixo decisivo é o escopo, não o acabamento. Um servidor construído em torno do seu próprio login só alcança as contas que você administra, por melhor que seja sua saída. Este responde à mesma pergunta para qualquer perfil público, e os campos voltam como arrays analisados que não custam nada para agregar.

O que este servidor não faz. Sem comentários, sem stories, sem reels além do que o feed reporta, sem mensagens diretas, sem busca por hashtag ou localização, e nada que escreva. Ele lê duas coisas bem.

FAQ

O que é um servidor MCP do Instagram?

Um servidor que expõe dados do Instagram como ferramentas que um cliente de IA pode chamar. O cliente envia uma chamada de ferramenta pelo Model Context Protocol, o servidor busca os dados e retorna JSON estruturado, e o modelo trabalha com o resultado e nunca vê uma página de HTML. Este expõe duas ferramentas somente leitura e roda remotamente. O cliente se conecta a uma URL e não inicia nenhum processo local.

Existe um servidor MCP oficial do Instagram?

A Meta não publica um de propósito geral. Existe um MCP oficial para publicidade da Meta, e ele cobre contas de anúncios e campanhas, não dados de perfil e posts. Todo o resto nesse espaço é construído por terceiros.

Quais dados estão no escopo?

Campos públicos de perfil e o feed público de posts, para contas públicas, por perfil. Uma conta privada ainda retorna seu cabeçalho, as contagens de seguidores e seguindo e um sinalizador private: true, mas sem biografia e sem posts, já que não há feed público para ler. Você é responsável por como usa os resultados, incluindo conformidade com os termos do Instagram e com a lei que se aplica a você.

Preciso hospedar ou executar algo?

Não. Este é um servidor MCP remoto em HTTP transmissível. Nada para instalar, sem ambiente Python, sem processo para reiniciar.

Os dados são ao vivo ou em cache?

Ao vivo. Cada chamada busca no momento da solicitação e carrega seu próprio requestMetadata.id. Duas chamadas idênticas são duas buscas separadas e não uma reprodução de uma cópia armazenada. Contadores como seguidores e curtidas acompanham a conta e se movem conforme ela se move.

Quantos posts posso obter?

Doze por chamada, uma página do Instagram, e páginas adicionais vêm de pagination.nextPageToken. Para uma conta pública, a consulta de perfil inclui os mesmos doze sem custo extra, então perguntas curtas sobre o feed muitas vezes não precisam de nenhuma chamada de posts.

O que acontece quando o Instagram muda sua marcação?

Nada do seu lado. Acompanhamos as mudanças e mantemos o esquema de resposta estável, e nomes e tipos de campos permanecem no lugar. Um campo sem valor fica ausente do item em vez de presente e nulo, e é por isso que campos opcionais devem ser lidos com um padrão.

Posso usar um servidor para várias plataformas?

Sim. O parâmetro apis aceita uma lista, e ?apis=instagram,tiktok,youtube dá ao seu agente três plataformas de uma vez.

Quais clientes funcionam?

Qualquer cliente MCP que suporte HTTP transmissível com cabeçalhos personalizados. As configurações acima são testadas. Clientes com suporte a OAuth podem adicionar a URL como um conector.

Links da HasData

Desenvolvimento

Este repositório é configuração e documentação para um servidor remoto. Não há etapa de build e nada para containerizar.

Ele carrega um teste de contrato. O README promete duas ferramentas com parâmetros específicos, e a lista de ferramentas upstream pode mudar sem um commit aqui, o que deixaria este arquivo silenciosamente mentindo para você. O teste afirma a promessa e roda semanalmente na CI, bem como a cada push.

HASDATA_API_KEY=your_key_here npm test

No PowerShell:

$env:HASDATA_API_KEY = "your_key_here"; npm test

A última verificação faz uma chamada real e custa 10 créditos, que é o preço de um canário que pode falhar pelo motivo certo. Listar ferramentas funciona com qualquer chave não vazia, e um teste que apenas lista ferramentas permanece verde com uma chave revogada.

Contribuindo

Correções nas tabelas de ferramentas e nos exemplos de resposta são a contribuição mais útil, porque são as partes que se desatualizam. Inclua a chamada que você fez e a resposta que obteve. Pull requests de forks executam a suíte sem chave, e as verificações ao vivo são puladas em vez de ficarem vermelhas.

Licença

MIT. Veja LICENSE.