Social APIS Hub

La API unificada para datos de redes sociales, diseñada para desarrolladores y agentes de IA.

Documentación

Servidor MCP de SocialAPIs Hub

Datos de Facebook e Instagram para agentes de IA — local (npx) o alojado (MCP remoto)

Sitio web • Documentación • Discord • npm

SDK oficiales: Python • JavaScript / TypeScript • Go

🚀 Inicio rápido

Agentes de IA (Cline, Claude Code, Cursor): sigue llms-install.md para una instalación y verificación paso a paso.

Un clic: usa el botón Instalar en Cursor de arriba — luego reemplaza YOUR_API_KEY en la configuración de MCP de Cursor con tu clave. También aparece en Smithery, cursor.directory, mcp.so y el Registro oficial de MCP (io.github.SocialAPIsHub/social-media-api).

Opción A — Alojado (MCP remoto, sin instalación)

Apunta cualquier cliente que admita servidores MCP remotos (HTTP Streamable) a:

https://mcp.socialapis.io/mcp

Autentica con tu clave de API de SocialAPIs Hub en un encabezado:

Authorization: Bearer YOUR_API_KEY

(x-api-token: YOUR_API_KEY también funciona.) El listado de herramientas funciona sin clave; las llamadas a herramientas la requieren. Ejemplo de configuración para clientes que aceptan URL + encabezados:

{
  "mcpServers": {
    "socialapis": {
      "url": "https://mcp.socialapis.io/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Opción B — Local (npx, stdio)

Instalación

npm install -g @socialapis/mcp

Configuración

Añade a tu configuración de Claude Desktop:

macOS:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

🔧 Configuración

Método 1: Argumento de línea de comandos (recomendado para Claude Desktop)

{
  "mcpServers": {
    "socialapis": {
      "command": "npx",
      "args": ["-y", "@socialapis/mcp", "YOUR_API_KEY"]
    }
  }
}

Método 2: Variable de entorno

# Set environment variable
export SOCIALAPIS_API_KEY=your_api_key_here

# Run without argument
npx @socialapis/mcp

Método 3: Archivo .env (para desarrollo)

# Copy example file
cp .env.example .env

# Edit with your values
nano .env

Archivo .env:

SOCIALAPIS_API_KEY=your_api_key_here
MCP_PROXY_URL=https://mcp.socialapis.io

Variables de entorno

Variable	Descripción	Predeterminado
`SOCIALAPIS_API_KEY`	Tu clave de API de SocialAPIs Hub	Ninguna (obligatoria)
`MCP_PROXY_URL`	URL del servidor proxy MCP	`https://mcp.socialapis.io`
`PORT`	Puerto del servidor HTTP	`3001`
`API_BASE_URL`	URL de la API de backend	`https://api.socialapis.io`

Obtener clave de API

Regístrate en socialapis.io
Ve al Panel de control
Copia tu clave de API
Reemplaza YOUR_API_KEY en la configuración

Probar

Reinicia Claude Desktop y pregunta:

Get Nike's Facebook page details

📋 Características

🌐 Una clave de API — Facebook e Instagram detrás de una única interfaz
🤖 Primero para IA — Diseñado para Claude, Cursor y agentes de IA
📊 Datos enriquecidos — Publicaciones, comentarios, métricas de interacción
🔍 Filtrado avanzado — Rangos de tiempo, paginación
🎯 Autenticación simple — Sin complejidad de OAuth
🧩 Salida estructurada — cada herramienta declara un esquema de salida y devuelve { result, creditsCharged, creditsRemaining }, para que los agentes puedan rastrear el gasto de créditos directamente
🛡️ Anotaciones de solo lectura — todas las herramientas están marcadas como readOnlyHint, para que los clientes puedan omitir las solicitudes de confirmación
⚡ Rápido — Red global de borde
🔒 Seguro — Las claves de API permanecen locales

🛠️ Herramientas disponibles

12 herramientas que cubren 47 acciones en Facebook e Instagram. Cada herramienta agrupa un recurso y toma un argumento action; cada acción se asigna a un endpoint REST en api.socialapis.io. Las descripciones de las herramientas enumeran cada acción, los parámetros que necesita y su costo en créditos.

Herramienta	Acciones
`facebook_page`	`details` (seguidores, información de contacto, categoría; `exact_followers_count=true` cuesta 5 créditos), `id`, `posts` (`limit` 3-9, filtros de fecha), `videos` (`limit` 6-12), `reels`
`facebook_group`	`details`, `id`, `posts` (`limit` 3-9, filtros de fecha), `videos`
`facebook_post`	`details`, `details_extended` (recuentos de vistas, URL de videos, metadatos de audio), `id`, `attachments` (5 créditos), `video`, `comments`, `comment_replies`
`facebook_search`	`pages`, `people`, `posts`, `videos`, `locations` (UID de ubicación para las otras búsquedas)
`facebook_ads`	`search` (anuncios por palabra clave, página, país, estado), `keywords` (anunciantes para una palabra clave), `page_details`, `archive_details`, `countries`
`facebook_marketplace`	`search` (precio, ubicación, categoría, filtros de condición), `vehicles`, `rentals`, `listing`, `seller`, `categories`, `city_coordinates`
`facebook_media_download`	URL de descarga para imágenes y videos de Facebook
`instagram_profile`	`details`, `id`, `posts`, `reels`, `highlights`, `highlight_details`
`instagram_post`	`details`, `id` (código corto desde una URL de publicación)
`instagram_reels`	`feed`, `by_audio`
`instagram_search`	Usuarios populares, hashtags y lugares para una palabra clave
`instagram_location`	`posts` (recientes o principales), `nearby`

Ejemplo de llamada: facebook_page con {"action": "posts", "link": "https://www.facebook.com/nike", "limit": 9}.

Actualización desde 1.x: los 47 nombres de herramientas anteriores (facebook_get_page_details, instagram_get_profile_posts, …) siguen funcionando cuando se llaman directamente, por lo que los prompts y scripts existentes siguen ejecutándose. Ya no se enumeran. Si tu cliente aprueba automáticamente herramientas por nombre, añade los nuevos nombres.

Aún no compatible

Solo Facebook e Instagram están disponibles hoy. TikTok, X / Twitter, LinkedIn y YouTube están en la hoja de ruta sin fechas comprometidas — las herramientas para ellos aparecerán aquí solo cuando se lancen.

Sigue la hoja de ruta de plataformas en socialapis.io/api-sources.

💡 Ejemplos de uso

Cada prompt a continuación es una sesión real de Claude Desktop. Algunos son patrones de una sola llamada a herramienta ("dame X"); otros requieren que Claude encadene múltiples llamadas + agregue los resultados (se indica donde corresponde).

Patrones de una sola llamada (rápidos, económicos)

What's Nike's follower count on Facebook?
→ Uses facebook_page action=details (1 credit)

Get the latest 9 posts from facebook.com/EngenSA
→ Uses facebook_page action=posts with limit=9 (1-3 credits depending on actual returned count)

Show me the Meta ads currently running for "Apple Vision Pro" in Germany
→ Uses facebook_ads action=search (1 credit)

Patrones de múltiples llamadas (Claude los orquesta — pero es más lento + más costoso)

Compare engagement on Nike vs Adidas's last 9 Facebook posts
→ Claude calls facebook_page action=posts twice (~2-6 credits total),
  aggregates reactions/comments/shares per post, returns a comparison.

What are people saying in the comments on Coca-Cola's last 3 posts?
→ Claude calls facebook_page action=posts (1 credit) then
  facebook_post action=comments 3 times (3 credits) and summarizes.

Show me marketplace listings for "PlayStation 5" under $400 in Berlin
→ Claude calls facebook_marketplace action=city_coordinates (1 credit) +
  facebook_marketplace action=search with filters (1 credit).

Lo que este servidor MCP NO hace

Algunas consultas parecen naturales en un chat ("comparar interacción durante el último mes") pero requieren agregaciones que la API no expone como una sola herramienta aún. Claude aún puede responderlas, pero se expandirá en muchas llamadas a herramientas — lo cual es lento + costoso.

Forma de consulta	Por qué es difícil
"Tasa de interacción en los últimos 30 días" para una página	Requiere obtener cada publicación en el rango de fechas (paginado, `limit` limitado a 9 por llamada) y calcular la interacción por publicación. Alcanza el presupuesto de llamadas a herramientas del LLM en páginas ocupadas.
"Comparar tasas de interacción entre Marca A, B, C durante el último mes"	Mismo problema, 3× — una obtención paginada por marca, luego matemática de comparación. Funciona para ventanas pequeñas; lento para "último mes" en páginas de alto volumen.
Archivo histórico más antiguo de lo que Facebook mismo sirve	Mostramos lo que Facebook hace visible públicamente. Las publicaciones que salieron del feed visible de Facebook no son recuperables.
Series temporales del lado del servidor (interacción diaria, crecimiento semanal)	Aún no — en la hoja de ruta como un futuro endpoint `engagement-stats` con agregación integrada.

Si tu caso de uso se asigna a uno de estos patrones y quieres la agregación precalculada en lugar de orquestada por LLM, contacta al soporte con la consulta específica — estamos priorizando el endpoint de agregación según la demanda de los clientes.

🏗️ Arquitectura

Claude Desktop
    ↓
@socialapis/mcp (local MCP client)
    ↓
https://mcp.socialapis.io (global proxy)
    ↓
https://api.socialapis.io (data API)

¿Por qué esta arquitectura?

✅ Baja latencia (red global de borde)
✅ Alta confiabilidad (99.9% de tiempo de actividad)
✅ Limitación de velocidad automática
✅ Caché inteligente
✅ Tu clave de API permanece local

🔧 Desarrollo

Configuración local

# Clone repository
git clone https://github.com/SocialAPIsHub/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Run MCP client
npm start YOUR_API_KEY

# Run HTTP proxy server
npm run serve

Estructura del proyecto

mcp-server/
├── src/
│   ├── tools.js          # The 47 endpoint definitions (one per action)
│   └── groups.js         # Groups them into the 12 listed tools
├── mcp-wrapper.js        # MCP client (runs locally)
├── server.js             # HTTP proxy server
├── package.json
├── Dockerfile
└── README.md

Pruebas

# Test MCP client locally
node mcp-wrapper.js YOUR_API_KEY

# Test HTTP proxy
curl http://localhost:3001/health
curl http://localhost:3001/tools

# Test specific tool
curl -X POST http://localhost:3001/proxy \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"facebook_page","arguments":{"action":"details","link":"https://facebook.com/nike"}}'

📊 Precios

Plan	Créditos / mes	Precio
Gratis	200	$0
Pro	1,500	$4.99
Ultra	30,000	$49
Mega	120,000	$179
Empresarial	Personalizado	Contáctanos

La mayoría de las herramientas cuestan 1 crédito por llamada; cada descripción de herramienta indica su precio exacto. Planes actuales: socialapis.io/pricing.

Ver precios detallados →

🤝 Contribuciones

¡Agradecemos las contribuciones! Consulta CONTRIBUTING.md para más detalles.

Guía rápida de contribución

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/amazing-feature)
Confirma tus cambios (git commit -m 'Add amazing feature')
Sube a la rama (git push origin feature/amazing-feature)
Abre una solicitud de extracción (Pull Request)

📖 Documentación

Documentación completa
Referencia de API
Guía de MCP
Ejemplos
Habilidad de agente: enseña a Claude Code, Cursor, Codex y otros agentes de codificación a usar SocialAPIs Hub (npx skills add SocialAPIsHub/skills)

💬 Soporte

📧 Correo electrónico: support@socialapis.io
💬 Discord: discord.gg/D5bQskrwV
🐛 Problemas: Problemas de GitHub
📚 Documentación: docs.socialapis.io

🗺️ Hoja de ruta

Lanzado:

Próximamente:

Soporte de TikTok
Soporte de X (Twitter)
Soporte de LinkedIn
Soporte de YouTube
Analítica avanzada — endpoints de agregación del lado del servidor (interacción a lo largo del tiempo, comparaciones de marcas) para que los patrones de múltiples llamadas se conviertan en una sola llamada a herramienta
Webhooks en tiempo real — notificaciones push sobre nuevas publicaciones / umbrales de interacción
Integración con LangChain

Las prioridades de plataforma cambian según la demanda de los clientes. La forma más rápida de impulsar algo en la cola es enviar un correo a support@socialapis.io o un mensaje directo a @socialapis en Telegram con el caso de uso.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT — consulta el archivo LICENCIA para más detalles.

🙏 Agradecimientos

Construido con Protocolo de Contexto de Modelo
Impulsado por Anthropic Claude
Inspirado por la comunidad de agentes de IA

📇 Listado en

También en el Registro oficial de MCP, Smithery, LobeHub, mcp.so, mcpservers.org, cursor.directory y awesome-remote-mcp-servers.

🌟 Historial de estrellas

Hecho con ❤️ por el equipo de SocialAPIs Hub

Sitio web • Twitter • Discord

SDK de Python • SDK de JS • SDK de Go