Servidor MCP de Instagram

Un servidor alojado de Protocolo de Contexto de Modelo (MCP) que ofrece a Claude, Cursor, Windsurf y cualquier otro cliente MCP dos herramientas de solo lectura para Instagram. Consulta un perfil público por su nombre de usuario y recorre su feed de publicaciones público, como JSON estructurado.

Lee datos públicos de cuentas. No actúa como una cuenta. No hay nada que conectar y ninguna cuenta tuya interviene en el flujo.

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

Contenido

• Qué necesitas

• Inicio rápido

• Ejemplos de indicaciones

• Herramientas

• Errores y casos de fallo

• Precios, capa gratuita y límites

• Selección de herramientas

• Comparativa

• Preguntas frecuentes

• Enlaces de HasData

• Desarrollo

• Contribuciones

• Licencia

Related MCP server: instagram-mcp

Qué necesitas

Un cliente MCP que hable HTTP transmisible con cabeceras personalizadas. Una clave de API de HasData desde el panel de control, gratuita de crear sin tarjeta, y la prueba cubre 100 llamadas. Nada más. Este es un servidor remoto, así que el camino más sencillo es una URL y una cabecera, sin contenedor que ejecutar. Un cliente que solo admita stdio puede usar el lanzador @hasdata/instagram-mcp (npm) o hasdata-instagram-mcp (PyPI) en su lugar.

Inicio rápido

La URL del servidor es la misma para todos los clientes. Lo ejecutamos de forma práctica en Claude Code y Claude Desktop. Los demás bloques siguen el formato documentado que cada cliente tiene para un servidor remoto.

Los clientes con soporte OAuth pueden añadir la misma URL como conector e iniciar sesión sin poner una clave en un archivo de configuración.

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

Claude Desktop solo carga servidores locales (stdio) desde su archivo de configuración, por lo que llega a un servidor remoto mediante un lanzador stdio. El paquete @hasdata/instagram-mcp es ese lanzador, y lee la clave del entorno.

claude_desktop_config.json:

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

¿Python en lugar de Node? Sustituye el lanzador por el paquete de PyPI, que uvx ejecuta sin instalación manual:

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

Un cliente con soporte OAuth puede añadir en su lugar la URL como conector personalizado y omitir el lanzador.

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

Ejemplos de indicaciones

Cada una de estas es una llamada de herramienta salvo que el recuento indique lo contrario.

Obtén el perfil de @nasa y dime el número de seguidores, la categoría y todos los enlaces de la biografía.

Una llamada, 10 créditos. Para una cuenta pública, la respuesta del perfil ya incluye las doce publicaciones más recientes, así que una consulta posterior sobre la actividad reciente no necesita una segunda llamada.

Compara @nasa, @natgeo y @bbcearth en cuanto a seguidores, publicaciones publicadas y si cada una es una cuenta de empresa.

Tres llamadas, 30 créditos. Una por nombre de usuario.

Recorre las últimas cincuenta publicaciones de @nasa y enumera cada hashtag con la frecuencia con la que aparece.

Cinco llamadas, 50 créditos. Llegan doce publicaciones por llamada, y cincuenta requieren cinco páginas.

Para las últimas doce publicaciones de @natgeo, dame los me gusta, los comentarios y las cuentas mencionadas en cada pie de foto.

Una llamada, 10 créditos. Los recuentos de interacción y las menciones vienen analizados en los objetos de publicación.

Dos cosas hacen que esto funcione. Los hashtags y las menciones llegan como matrices extraídas del pie de foto, y un agente los cuenta en lugar de ejecutar una expresión regular sobre el texto. Y una consulta de perfil devuelve el feed reciente en la misma respuesta. Por eso tantas preguntas de investigación se resuelven en una sola llamada.

Herramientas

Dos herramientas, ambas de solo lectura, ambas basadas en el nombre de usuario de una cuenta pública. Las muestras siguientes están recortadas de llamadas reales, y los números en ellas cambian a medida que las cuentas publican. Léelas como formas. Cada nombre de herramienta enlaza con su referencia de endpoint.

Las muestras son la carga útil, no la respuesta completa. Un resultado de tools/call lleva un bloque de texto, y ese texto es en sí mismo JSON que contiene url, status, text y json, con los datos extraídos bajo json. Desde una respuesta JSON-RPC cruda, la ruta es result.content[0].text, analizada, y luego .json. Un cliente de chat lo desenvuelve por ti; el código que habla directamente con el endpoint no lo hace.

Obtener un perfil de Instagram

hasdata_instagram_profile_getInstagramProfile

Un perfil público por nombre de usuario.

Devuelve id, username, fullName, biography, businessCategory, verified, isBusinessAccount y isProfessionalAccount, los contadores followersCount, followsCount, postsCount, highlightsCount e igtvVideoCount, tanto profilePicUrl como profilePicUrlHD, y las matrices latestPosts, latestIgtvVideos y relatedProfiles.

Los campos básicos de identidad y los contadores de seguidores y seguidos llegan para toda cuenta pública. Los campos adicionales dependen de lo que la propia cuenta exponga, así que lee los opcionales con un valor predeterminado.

Los enlaces viven en dos campos que no son lo mismo. bioLinks es la matriz de todos los enlaces de la biografía. externalUrls es una sola cadena a pesar del nombre en plural, y contiene el enlace principal, a veces con una barra final que la versión en matriz no tiene. Lee bioLinks cuando los quieras todos.

latestPosts e latestIgtvVideos no llevan campos idénticos. Las entradas de vídeo añaden taggedUsers, y los objetos de publicación aquí omiten el productType que incluye la herramienta de publicaciones. El código que recorra ambas matrices con un solo analizador debe tratar las claves adicionales como opcionales.

{
  "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 es la propia lista de sugerencias de Instagram para la cuenta y llega a unas pocas docenas de entradas. Es una forma económica de ampliar un conjunto de competidores sin adivinar nombres de usuario.

Obtener publicaciones de Instagram

hasdata_instagram_posts_getInstagramPosts

El feed de publicaciones público de un nombre de usuario, página por página.

limit es un tope aproximado, no un recuento exacto. Doce publicaciones son una página de Instagram y el techo máximo para una sola llamada, y limit: 50 devuelve doce. Por debajo del techo, el recuento se acerca al número que pediste sin coincidir siempre, y cuánto se acerca depende de la cuenta. Medido en @nasa, un límite de 2 devolvió 4 publicaciones, 6 devolvió 6, 11 devolvió 10 y 13 devolvió 12. Trátalo como "no más de aproximadamente esta cantidad" y lee la longitud de la matriz en lugar de asumirla.

La respuesta repite los campos de identidad de la cuenta junto a las publicaciones. username, id, fullName, verified y ambas URL de avatar llegan en cada página. Útil para etiquetar filas, y conviene saberlo antes de hacer una llamada de perfil aparte para obtenerlos.

Cada publicación lleva id, shortcode, caption, type, productType, hashtags, mentions, likesCount, commentsCount, timestamp, url, displayUrl, images, dimensionsWidth, dimensionsHeight, ownerId y 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"
  }
}

Los hashtags y las menciones conservan sus prefijos # y @, lo cual importa si los vas a cruzar con una lista que hayas creado tú mismo. morePostsAvailable es el indicador sobre el que ramificar al paginar, y hasdataLink es la misma página siguiente expresada como URL REST, útil cuando quieres reproducir a mano la llamada de un agente.

Errores y casos de fallo

Tu cliente casi nunca ve un código de error HTTP de una llamada de herramienta. La capa MCP responde 200 y coloca el fallo dentro del resultado, con isError establecido en true y el motivo como texto. El agente lee un mensaje donde podrías esperar una línea de estado.

Una clave incorrecta aparece como salida de herramienta, no como conexión fallida. Enumerar herramientas acepta cualquier clave no vacía, y el cliente completa su handshake y muestra verde. La primera llamada de herramienta vuelve entonces con isError: true y el texto HasData API error: 401 Unauthorized. Presta atención a esa cadena, porque nada antes en el flujo informa del problema.

Una clave ausente es el único error HTTP real. La autorización se ejecuta antes que cualquier herramienta, y la propia conexión falla con 401.

Un argumento que rompe el esquema se rechaza antes de convertirse en solicitud. El servidor responde con isError: true y el texto MCP error -32602: Input validation error, nombrando el campo. No se obtiene nada y no se cobra nada.

Un nombre de usuario que no se resuelve es un error limpio, no datos vacíos. Devuelve isError: true con HasData API error: 400 Bad Request y requestMetadata.status establecido en error. Este es el caso bueno, porque el fallo es inequívoco. Comprueba el indicador en lugar de la longitud de la matriz.

Una cuenta cuyos datos no son públicos no devuelve feed de publicaciones. Las herramientas cubren cuentas públicas, y no hay nada que leer en una que no lo sea. Trata un latestPosts ausente como fuera de alcance y no como un feed vacío.

Los resultados que llevan datos también llevan un requestMetadata.id que vale la pena citar en soporte, además de enlaces html y json al artefacto almacenado de esa llamada exacta.

Precios, capa gratuita y límites

Cada herramienta de Instagram cuesta 10 créditos por llamada correcta. El tamaño de la respuesta no cambia el precio. Un perfil con doce publicaciones adjuntas cuesta lo mismo que uno sin ninguna.

La prueba gratuita incluye 1.000 créditos durante 30 días sin tarjeta, o 100 llamadas de Instagram. Después, una cuenta activa sigue recibiendo 100 créditos de recarga cada día siempre que su saldo baje de 100, de modo que un agente de bajo volumen funciona en el plan gratuito indefinidamente.

Los planes de pago empiezan en $49 al mes por 200.000 créditos, o 20.000 llamadas. El precio unitario baja con el volumen: de $2,45 por cada 1.000 llamadas en el plan inicial a $0,99 en Business, $0,83 en Growth y $0,75 en los planes de alto volumen.

Tu plan también fija la concurrencia. La prueba gratuita permite 1 solicitud a la vez, Startup 15, Business 30, Growth 50, y los planes de alto volumen van de 200 a 1.500. Gestiona el caso de desbordamiento de forma defensiva en cualquier proceso no supervisado, porque un agente que se despliegue por varias cuentas llegará al techo antes que tú.

Pasar de página cuesta una llamada cada vez. Un prompt que recorre cien publicaciones en dos cuentas equivale a dieciocho llamadas y 180 créditos. La prueba rinde más comparando perfiles que haciendo rastreos profundos del feed.

Tool selection

?apis=instagram expone exactamente estas dos herramientas. El parámetro admite una lista, y ?apis=instagram,tiktok,youtube le da a tu agente tres plataformas sociales a la vez. Si eliminas el parámetro, obtienes todo lo que HasData expone, que actualmente son 57 herramientas.

Una lista reducida suele ser la mejor opción por defecto. Un modelo que elige entre dos herramientas acierta con más frecuencia que uno que elige entre cincuenta y siete, y las propias descripciones de las herramientas consumen contexto en cada turno.

La comparación entre plataformas es el motivo habitual para ampliar la lista. Haz la misma pregunta a una cuenta de Instagram y a una de TikTok, y será un solo prompt una vez que ambas estén expuestas.

Cómo se compara

Casi todos los servidores MCP de Instagram hacen algo distinto de este, y eso hace que la elección sea inusualmente clara.

Los populares operan una cuenta. Algunos envuelven la Instagram Graph API para publicar posts, leer comentarios y gestionar las cuentas que administras. Otros se encargan de los mensajes directos. Los servidores de análisis de engagement piden INSTAGRAM_USERNAME e INSTAGRAM_PASSWORD en un bloque env, según sus propias instrucciones de configuración, porque inician sesión y navegan como tú. Todos ellos son la herramienta adecuada cuando la tarea es gestionar una cuenta que controlas.

Este servidor nunca inicia sesión como nadie, lo cual es un trabajo distinto. Cada pregunta que responde es sobre una cuenta que no te pertenece, y la llamada es idéntica sea cual sea esa cuenta.

Dos filas lo deciden. Si necesitas publicar, comentar o responder, este servidor no puede ayudarte en absoluto. Si necesitas los mismos campos en cien cuentas con las que no tienes ninguna relación, un servidor construido alrededor de tus propias credenciales tampoco puede ayudarte.

El eje decisivo es el alcance, no el acabado. Un servidor construido en torno a tu propio inicio de sesión solo puede llegar a las cuentas que administras, por muy buena que sea su salida. Este responde la misma pregunta para cualquier cuenta pública, y los campos vuelven como arrays analizados que no cuestan nada de agregar.

Lo que este servidor no hace. Nada de comentarios, ni stories, ni reels más allá de lo que informa el feed, ni mensajes directos, ni búsqueda por hashtag o ubicación, y nada que escriba. Lee bien dos cosas.

Preguntas frecuentes

¿Qué es un servidor MCP de Instagram?

Un servidor que expone datos de Instagram como herramientas que un cliente de IA puede invocar. El cliente envía una llamada de herramienta a través del Model Context Protocol, el servidor obtiene los datos y devuelve JSON estructurado, y el modelo trabaja con el resultado sin ver nunca una página de HTML. Este expone dos herramientas de solo lectura y se ejecuta de forma remota. El cliente se conecta a una URL y no inicia ningún proceso local.

¿Existe un servidor MCP oficial de Instagram?

Meta no publica uno de propósito general. Existe un MCP oficial para la publicidad de Meta, y cubre cuentas y campañas publicitarias, no datos de perfiles y publicaciones. Todo lo demás en este espacio lo ha construido otra persona.

¿Qué datos abarca?

Campos de perfil públicos y el feed público de publicaciones, para cuentas públicas, por nombre de usuario. Una cuenta privada sigue devolviendo su cabecera, los contadores de seguidores y seguidos y un indicador private: true, pero sin biografía ni publicaciones, porque no hay un feed público que leer. Eres responsable de cómo utilices los resultados, incluido el cumplimiento de los términos de Instagram y de la ley que te sea aplicable.

¿Necesito alojar o ejecutar algo?

No. Es un servidor MCP remoto sobre streamable HTTP. Nada que instalar, sin entorno de Python, sin procesos que reiniciar.

¿Los datos son en vivo o en caché?

En vivo. Cada llamada obtiene los datos en el momento de la solicitud y lleva su propio requestMetadata.id. Dos llamadas idénticas son dos obtenciones separadas y no una reproducción de una copia almacenada. Contadores como seguidores y me gusta siguen a la cuenta y se mueven con ella.

¿Cuántas publicaciones puedo obtener?

Doce por llamada, una página de Instagram, y las páginas adicionales vienen de pagination.nextPageToken. Para una cuenta pública, la consulta de perfil incluye esos mismos doce sin coste adicional, por lo que las preguntas cortas sobre el feed a menudo no necesitan ninguna llamada de publicaciones.

¿Qué ocurre cuando Instagram cambia su marcado?

Nada por tu parte. Nosotros seguimos los cambios y mantenemos estable el esquema de respuesta, y los nombres y tipos de los campos se quedan igual. Un campo sin valor está ausente del elemento en lugar de estar presente y nulo, y por eso los campos opcionales deben leerse con un valor por defecto.

¿Puedo usar un solo servidor para varias plataformas?

Sí. El parámetro apis admite una lista, y ?apis=instagram,tiktok,youtube le da a tu agente tres plataformas a la vez.

¿Qué clientes funcionan?

Cualquier cliente MCP que admita streamable HTTP con cabeceras personalizadas. Las configuraciones anteriores están probadas. Los clientes con soporte de OAuth pueden añadir la URL como conector en su lugar.

Enlaces de HasData

Desarrollo

Este repositorio es configuración y documentación para un servidor remoto. No hay paso de compilación ni nada que contenerizar.

Sí incluye una prueba de contrato. El README promete dos herramientas con parámetros específicos, y la lista de herramientas upstream puede cambiar sin un commit aquí, lo que dejaría este archivo mintiéndote en silencio. La prueba verifica esa promesa y se ejecuta semanalmente en CI, además de en cada push.

HASDATA_API_KEY=your_key_here npm test

En PowerShell:

$env:HASDATA_API_KEY = "your_key_here"; npm test

La última comprobación hace una llamada real y cuesta 10 créditos, que es el precio de un canario que puede fallar por la razón correcta. Listar herramientas funciona con cualquier clave no vacía, y una prueba que solo liste herramientas seguirá en verde con una clave revocada.

Contribuciones

Las correcciones de las tablas de herramientas y de los ejemplos de respuesta son la contribución más útil, porque son las partes que se desactualizan. Incluye la llamada que hiciste y la respuesta que obtuviste. Las pull requests desde forks ejecutan la suite sin clave, y las comprobaciones en vivo se omiten en lugar de ponerse en rojo.

Licencia

MIT. Consulta LICENSE.