HasData Instagram MCP Server

Servidor MCP de Instagram

Un servidor de Model Context Protocol (MCP) alojado que brinda a Claude, Cursor, Windsurf y cualquier otro cliente MCP dos herramientas de solo lectura para Instagram. Busca un perfil público por 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 involucrada en ningún punto del flujo.

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

Contenido

• Lo que necesitas
• Inicio rápido
• Ejemplos de indicaciones
• Herramientas
• Errores y rutas de fallo
• Precios, plan gratuito y límites
• Selección de herramientas
• Cómo se compara
• Preguntas frecuentes
• Enlaces de HasData
• Desarrollo
• Contribuciones
• Licencia

Lo que necesitas

Un cliente MCP que hable HTTP transmisible con encabezados personalizados. 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 simple es una URL y un encabezado, sin contenedor que ejecutar. Un cliente solo-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 cada cliente. Lo ejecutamos de forma práctica en Claude Code y Claude Desktop. Los otros bloques siguen el formato documentado de cada cliente para un servidor remoto.

Los clientes con soporte OAuth pueden agregar 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"

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

Ejemplos de indicaciones

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

Obtén el perfil de @nasa y dime el número de seguidores, la categoría y cada enlace en 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, por lo que una pregunta de seguimiento sobre actividad reciente no necesita una segunda llamada.

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

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

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

Cinco llamadas, 50 créditos. Doce publicaciones llegan por llamada, y cincuenta requiere cinco páginas.

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

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

Dos cosas hacen que esto funcione. Los hashtags y las menciones llegan como matrices analizadas del pie de foto, y un agente las cuenta en lugar de ejecutar una expresión regular sobre prosa. Y una búsqueda 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 un nombre de usuario de cuenta pública. Las muestras a continuación 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 a su referencia de endpoint.

Las muestras son el payload, no la respuesta completa. Un resultado 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, analizado, luego .json. Un cliente de chat lo desenvuelve por ti, y 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 y igtvVideoCount, tanto profilePicUrl como profilePicUrlHD, y las matrices latestPosts, latestIgtvVideos y relatedProfiles.

Los campos de identidad centrales y los recuentos de seguidores y seguidos vuelven para cada cuenta pública. Los campos más allá de eso 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 cada enlace en 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 de matriz no tiene. Lee bioLinks cuando los quieras todos.

latestPosts y latestIgtvVideos no llevan campos idénticos. Las entradas de video agregan taggedUsers, y los objetos de publicación aquí omiten el productType que la herramienta de publicaciones incluye. El código que recorre ambas matrices con un solo analizador tiene que 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 para un nombre de usuario, página por página.

limit es un tope aproximado más que un recuento exacto. Doce publicaciones es una página de Instagram y el techo duro para una sola llamada, y limit: 50 devuelve doce. Por debajo del techo, el recuento aterriza cerca del número que pediste sin coincidir siempre, y qué tan cerca 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 asumirlo.

La respuesta repite los campos de identidad de la cuenta junto con las publicaciones. username, id, fullName, verified y ambas URL de avatar llegan en cada página. Útil para etiquetar filas, y vale la pena saberlo antes de hacer una llamada de perfil separada 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 mantienen sus prefijos # y @, lo que importa si los estás uniendo contra una lista que construiste tú mismo. morePostsAvailable es el indicador para ramificar al paginar, y hasdataLink es la misma página siguiente expresada como URL REST, útil cuando quieres reproducir la llamada de un agente a mano.

Errores y rutas de fallo

Tu cliente casi nunca ve un código de error HTTP de una llamada de herramienta. La capa MCP responde 200 y pone 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. Listar herramientas acepta cualquier clave no vacía, y el cliente completa su protocolo de enlace y muestra verde. La primera llamada de herramienta luego vuelve con isError: true y el texto HasData API error: 401 Unauthorized. Vigila esa cadena, porque nada antes en el flujo informa el problema.

Una clave faltante es el único error HTTP real. La autorización se ejecuta antes de cualquier herramienta, y la conexión misma 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. Nada se obtiene y nada se cobra.

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 establecidos en error. Este es el buen caso, porque el fallo es inequívoco. Prueba 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 faltante 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, más enlaces html y json al artefacto almacenado de esa llamada exacta.

Precios, plan gratuito y límites

Cada herramienta de Instagram cuesta 10 créditos por llamada exitosa. 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 es 1,000 créditos durante 30 días sin tarjeta, o 100 llamadas de Instagram. Después de eso, una cuenta activa sigue recibiendo 100 créditos recargados cada día cuando su saldo cae por debajo de 100, por lo que un agente de bajo volumen se ejecuta en el plan gratuito indefinidamente.

Los planes de pago comienzan en $49 al mes por 200,000 créditos, o 20,000 llamadas. El precio unitario baja con el volumen, desde $2.45 por 1,000 llamadas en el plan de entrada hasta $0.99 en Business, $0.83 en Growth y $0.75 en los planes de alto volumen más grandes.

Tu plan también establece 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. Maneja el caso de desbordamiento de forma defensiva en cualquier cosa desatendida, porque un agente que se expande entre nombres de usuario alcanzará el techo antes que tú.

Paginación cuesta una llamada cada vez. Una indicación que recorre cien publicaciones en dos cuentas es dieciocho llamadas y 180 créditos. La prueba llega más lejos en comparaciones de perfiles que en rastreos profundos de feeds.

Selección de herramientas

?apis=instagram expone exactamente estas dos herramientas. El parámetro acepta una lista, y ?apis=instagram,tiktok,youtube le da a tu agente tres plataformas sociales a la vez. Omite el parámetro y 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 descripciones de las herramientas consumen contexto en cada turno.

La comparación entre plataformas es la razón habitual para ampliar la lista. Haz la misma pregunta a un perfil de Instagram y a un perfil de TikTok y es una sola instrucción una vez que ambas están expuestas.

Cómo se compara

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

Los populares operan una cuenta. Algunos envuelven la API de Graph de Instagram para publicar publicaciones, leer comentarios y gestionar las cuentas que administras. Otros manejan mensajes directos. Los servidores de análisis de interacción piden INSTAGRAM_USERNAME y INSTAGRAM_PASSWORD en un bloque de entorno, según sus propias instrucciones de configuración, porque inician sesión y navegan como tú. Todos esos son la herramienta adecuada cuando el trabajo es gestionar una cuenta que controlas.

Este servidor nunca inicia sesión como nadie, lo cual es un trabajo diferente. Cada pregunta que responde es sobre un perfil que no posees, y la llamada es idéntica sea cual sea ese perfil.

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

El eje decisivo es el alcance, no el pulido. Un servidor construido alrededor de 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 perfil público, y los campos vuelven como matrices analizadas que no cuestan nada de agregar.

Lo que este servidor no hace. Sin comentarios, sin historias, sin reels más allá de lo que informa el feed, sin mensajes directos, sin búsqueda de hashtags o ubicaciones, y nada que escriba. Lee dos cosas bien.

Preguntas frecuentes

¿Qué es un servidor MCP de Instagram?

Un servidor que expone datos de Instagram como herramientas que un cliente de IA puede llamar. El cliente envía una llamada de herramienta a través del Protocolo de Contexto de Modelo, el servidor obtiene los datos y devuelve JSON estructurado, y el modelo trabaja con el resultado y nunca ve 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. Hay un MCP oficial para publicidad de Meta, y cubre cuentas publicitarias y campañas, no datos de perfiles y publicaciones. Todo lo demás en este espacio lo construye otra persona.

¿Qué datos están incluidos?

Campos públicos de perfil y el feed público de publicaciones, para cuentas públicas, por perfil. Una cuenta privada aún devuelve su cabecera, los contadores de seguidores y seguidos y un indicador private: true, pero sin biografía y sin publicaciones, ya que no hay feed público que leer. Eres responsable de cómo usas los resultados, incluido el cumplimiento de los términos de Instagram y de la ley que te aplica.

¿Necesito alojar o ejecutar algo?

No. Este es un servidor MCP remoto en HTTP transmisible. Nada que instalar, sin entorno de Python, sin proceso 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 las mismas doce sin coste adicional, así que las preguntas cortas sobre el feed a menudo no necesitan ninguna llamada de publicaciones.

¿Qué ocurre cuando Instagram cambia su marcado?

Nada de tu lado. Seguimos los cambios y mantenemos estable el esquema de respuesta, y los nombres y tipos de campos permanecen igual. Un campo sin valor está ausente del elemento en lugar de presente y nulo, y por eso los campos opcionales deben leerse con un valor predeterminado.

¿Puedo usar un servidor para varias plataformas?

Sí. El parámetro apis acepta 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 HTTP transmisible con cabeceras personalizadas. Las configuraciones anteriores están probadas. Los clientes con soporte 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.

Sin embargo, incluye una prueba de contrato. El README promete dos herramientas con parámetros específicos, y la lista de herramientas ascendente puede cambiar sin un commit aquí, y eso dejaría este archivo mintiéndote silenciosamente. La prueba afirma la promesa y se ejecuta semanalmente en CI, así como 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 lista herramientas se mantiene en verde con una revocada.

Contribuciones

Las correcciones a las tablas de herramientas y a los ejemplos de respuesta son la contribución más útil, porque son las partes que se desvían. Incluye la llamada que hiciste y la respuesta que obtuviste. Las solicitudes de extracción de bifurcaciones ejecutan el conjunto sin clave, y las comprobaciones en vivo se omiten en lugar de ponerse en rojo.

Licencia

MIT. Ver LICENCIA.