Opengraph.io

Datos de Opengraph, web scraping y funciones de captura de pantalla en una práctica herramienta MCP

Documentación

Servidor MCP de OpenGraph (og-mcp)

og‑mcp es un servidor de Model‑Context‑Protocol (MCP) que hace que todos los endpoints de la API de OpenGraph.io ( https://opengraph.io ) estén disponibles para agentes de IA (p. ej. Anthropic Claude, Cursor, LangGraph) a través de la interfaz estándar de MCP.

¿Por qué? Si ya usas OpenGraph.io para desplegar enlaces, extraer HTML, extraer texto de artículos o capturar capturas de pantalla, ahora puedes dar las mismas capacidades a tus agentes autónomos sin exponer claves de API en bruto.

Instalación global

Puedes instalar este paquete globalmente vía npm:

npm install -g opengraph-io-mcp

Instalación rápida

Instalador CLI (recomendado)

La forma más fácil de configurar OpenGraph MCP para cualquier cliente compatible:

# Interactive mode - guides you through setup
npx opengraph-io-mcp-install

# Direct mode - specify client and app ID
npx opengraph-io-mcp-install --client cursor --app-id YOUR_APP_ID

Clientes compatibles: cursor, claude-desktop, windsurf, vscode, zed, jetbrains

Extensión de Claude Desktop

Para usuarios de Claude Desktop, también puedes descargar la extensión .mcpb para instalación con un clic desde la página de lanzamientos.

Autenticación

El servidor MCP alojado admite dos métodos de autenticación:

Opción 1 — OAuth 2.1 (recomendado para implementaciones alojadas)

OAuth te permite autorizar el acceso a través de tu panel de OpenGraph.io sin copiar claves de API en archivos de configuración. El cliente MCP maneja todo el flujo de inicio de sesión en el navegador automáticamente.

Compatible con: clientes MCP que implementan el flujo de Código de Autorización + PKCE (Cursor, Claude Desktop 0.10+, VS Code con la extensión MCP).

Cuando el cliente se conecta sin credenciales, el servidor devuelve 401 con un encabezado WWW-Authenticate que apunta a:

GET /.well-known/oauth-protected-resource
→ { "authorization_servers": ["https://dashboard-api.opengraph.io"] }

El cliente luego obtiene los metadatos del servidor de autorización e inicia el flujo PKCE, redirigiendo tu navegador a https://dashboard.opengraph.io/oauth/consent donde inicias sesión y eliges qué clave de API autorizar.

No se necesita configuración del lado del cliente — el cliente descubre todo automáticamente.

Opción 2 — Encabezado `x-app-id` (legado / desarrollo local)

Pasa tu ID de aplicación como un encabezado HTTP. Adecuado para desarrollo local, CI o clientes que no admiten OAuth.

Reemplaza YOUR_OPENGRAPH_APP_ID con tu ID de aplicación de OpenGraph.io.

Configuración del cliente

Todas las configuraciones a continuación usan el transporte HTTPS alojado. OAuth es el enfoque recomendado para uso compartido/producción; la configuración del encabezado x-app-id se proporciona como alternativa.

OAuth (sin configuración estática necesaria)

Para clientes que admiten descubrimiento de OAuth, simplemente apunta a la URL alojada sin encabezados — el servidor solicitará autorización automáticamente:

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp"
    }
  }
}

Alternativa x-app-id

Si tu cliente no admite OAuth, o prefieres configuración estática:

Claude Desktop

Ubicación de configuración:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

Claude Code

Instalación con un comando:

claude mcp add --transport http --header "x-app-id: YOUR_OPENGRAPH_APP_ID" opengraph https://mcp.opengraph.io/mcp

Cursor

Ubicación de configuración: ~/.cursor/mcp.json

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

VS Code

Ubicación de configuración: .vscode/mcp.json (en el directorio de tu proyecto)

VS Code admite indicaciones de entrada para el manejo seguro de credenciales:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "opengraph-app-id",
      "description": "OpenGraph App ID",
      "password": true
    }
  ],
  "servers": {
    "opengraph": {
      "type": "http",
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "${input:opengraph-app-id}"
      }
    }
  }
}

Windsurf

Ubicación de configuración: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

Asistente de IA de JetBrains

Agrega a tu configuración de MCP del Asistente de IA de JetBrains:

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

Zed

Ubicación de configuración: ~/.config/zed/settings.json

Nota: Zed usa context_servers en lugar de mcpServers:

{
  "context_servers": {
    "opengraph": {
      "transport": "http",
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

Herramientas disponibles

Dos niveles de autenticación: Las herramientas de Datos y Generación de Imágenes funcionan con OAuth o con una clave de API simple x-app-id — incluido el transporte stdio y la extensión de Claude Desktop. Las herramientas de Auditoría de Sitio y Vista Previa de Enlaces requieren OAuth (solo transporte HTTPS alojado), ya que se facturan contra el plan de Auditoría de Sitio de tu organización en lugar de una sola clave de API.

Herramientas de Datos de OpenGraph.io

Todas las herramientas de extracción/metadatos usan por defecto la API v3 que habilita auto_render, auto_proxy y retry por defecto para mayores tasas de éxito en páginas complejas. Las herramientas query y extract usan v1.1 (ver notas).

Nombre de la herramienta	Endpoint de API	Descripción	Documentación
Obtener Datos OG	`/api/3.0/site/<URL>`	Obtiene metadatos de Open Graph, etiquetas inferidas de HTML y datos de vista previa social híbrida. Admite `use_ai`, `ai_sanitize`, carga-más, proxy/reintento y todos los valores predeterminados inteligentes de v3.	Docs
Obtener Datos de Extracción OG	`/api/3.0/scrape/<URL>`	Extrae HTML en bruto con opciones completas de renderizado v3, incluido desplazamiento hasta el final, clics de carga-más y saneamiento con IA.	Docs
Obtener Captura de Pantalla OG	`/api/3.0/screenshot/<URL>`	Captura una captura de pantalla. Admite `full_page`, `dark_mode`, `capture_delay`, `navigationTimeout`, `hideSelectors` y dimensiones de viewport personalizadas.	Docs
Obtener Consulta OG	`/api/1.1/query/<URL>`	Haz una pregunta en lenguaje natural sobre el contenido de una página. Usa v1.1 (100–200 créditos/solicitud) hasta que la ruta de facturación se actualice para v3.	Docs
Obtener Extracción OG	`/api/1.1/extract/<URL>`	Extrae elementos HTML específicos (h1, p, a, img, etc.) por nombre de etiqueta. Permanece en v1.1 — no existe una ruta GET de v3 para este endpoint.	Docs
Obtener Markdown OG	`/api/3.0/markdown/<URL>`	Convierte el HTML de cualquier URL a Markdown limpio. Elimina navegación/anuncios por defecto (`only_main_content: true`). Admite selectores `include_tags`/`exclude_tags`. Nota: Las páginas con mucho JS/SPA requieren `full_render: true` — el `auto_render` de v3 no se aplica a este endpoint.	Docs

Detección de idioma: Todas las herramientas envían accept_lang: auto por defecto, que refleja el encabezado Accept-Language de la solicitud. Pasa una etiqueta BCP 47 explícita (p. ej. en-US, fr) para anular.

Herramientas de Auditoría de Sitio y Vista Previa de Enlaces

Requiere OAuth 2.1 (ver Autenticación) y un plan activo de Auditoría de Sitio. Estas herramientas solo están disponibles a través del transporte HTTPS alojado — no están disponibles vía el encabezado x-app-id ni la extensión stdio/Claude Desktop, ya que necesitan la identidad de tu organización, no solo una clave de API.

Nombre de la herramienta	Descripción
Descubrir URLs del Sitio	Rastrea un dominio (sitemap + descubrimiento de enlaces) y devuelve cada página encontrada, agrupada por profundidad, junto con tu cuota de auditoría mensual restante.
Iniciar Auditoría de Sitio	Inicia una auditoría SEO/social asíncrona de múltiples páginas. Pasa una lista explícita de `urls[]` (del descubrimiento, un sitemap o un escaneo de rutas del código base) o deja que el backend rastree el dominio por sí mismo. Devuelve un `auditId` inmediatamente.
Obtener Estado de Auditoría de Sitio	Consulta una auditoría en curso (`QUEUED` → `CRAWLING` → `SCORING` → `COMPLETE`).
Obtener Informe de Auditoría de Sitio	Recupera el informe completo una vez finalizado: puntuación general (0–100), un resumen ejecutivo generado por IA, correcciones priorizadas, puntuaciones por página y tasas de cobertura de Open Graph.
Vista Previa de Auditoría de Página	Verificación instantánea y síncrona de una sola URL con puntuación y problemas. No consume cuota de auditoría.
Obtener Vista Previa de Enlace	Verificación instantánea y síncrona de cómo se renderizará una URL al compartirse — devuelve tarjetas de vista previa de Facebook, Twitter/X, LinkedIn y Google, además de una puntuación de calidad y lista de correcciones. No consume cuota de auditoría.

Herramientas de Generación de Imágenes

Nombre de la herramienta	Descripción
Generar Imagen	Crea imágenes profesionales: ilustraciones, diagramas (Mermaid/D2/Vega), iconos, tarjetas sociales o códigos QR
Iterar Imagen	Refina, modifica o crea variaciones de imágenes generadas existentes
Inspeccionar Sesión de Imagen	Recupera metadatos de sesión e historial de activos para sesiones de generación de imágenes
Exportar Activo de Imagen	Exporta activos de imagen generados como base64 en línea, con escritura opcional en disco cuando se ejecuta localmente

Generación de Imágenes

El servidor og-mcp incluye potentes capacidades de generación de imágenes impulsadas por IA, perfectas para crear tarjetas de redes sociales, diagramas de arquitectura, iconos y más.

Generar Imagen

Crea imágenes a partir de indicaciones en lenguaje natural o código de diagrama.

Tipos de imagen compatibles (kind):

illustration - Imágenes generadas por IA de propósito general
diagram - Diagramas técnicos a partir de sintaxis Mermaid, D2 o Vega
icon - Iconos y logotipos de aplicaciones
social-card - Imágenes OG optimizadas para compartir en redes sociales
qr-code - Códigos QR con estilo opcional

Relaciones de aspecto preestablecidas:

Social: og-image, twitter-card, twitter-post, linkedin-post, facebook-post, instagram-square, instagram-portrait, instagram-story, youtube-thumbnail
Estándar: wide, square, portrait
Iconos: icon-small, icon-medium, icon-large

Estilos preestablecidos: github-dark, github-light, notion, vercel, linear, stripe, neon-cyber, pastel, minimal-mono, corporate, startup, documentation, technical

Plantillas de diagramas: auth-flow, oauth2-flow, crud-api, microservices, ci-cd, gitflow, database-schema, state-machine, user-journey, cloud-architecture, system-context

Ejemplo de uso:

// Generate a social card
generateImage({
  prompt: "A modern tech startup hero image with abstract geometric shapes",
  kind: "social-card",
  aspectRatio: "og-image",
  stylePreset: "vercel",
  brandColors: ["#0070F3", "#000000"]
})

// Generate a diagram from Mermaid syntax
generateImage({
  prompt: "graph TD; A[User] --> B[API]; B --> C[Database]",
  kind: "diagram",
  diagramSyntax: "mermaid",
  stylePreset: "github-dark"
})

Iterar Imagen

Refina o modifica una imagen generada existente.

Casos de uso:

Editar partes específicas: "cambia el fondo a azul"
Aplicar cambios de estilo: "hazlo más minimalista"
Corregir problemas: "elimina el texto", "haz el icono más grande"
Recortar a coordenadas específicas

Ejemplo:

iterateImage({
  sessionId: "uuid-from-generate",
  assetId: "uuid-from-generate",
  prompt: "Change the primary color to #0033A0 and add a subtle drop shadow"
})

Inspeccionar Sesión de Imagen

Revisa los detalles de la sesión y encuentra IDs de activos para iteración.

Devuelve:

Metadatos de sesión (hora de creación, nombre, estado)
Lista de todos los activos con indicaciones, cadenas de herramientas y estado
Relaciones padre-hijo que muestran el historial de iteración

Ejemplo:

inspectImageSession({
  sessionId: "uuid-from-generate"
})

Exportar Activo de Imagen

Exporta un activo de imagen generado por ID de sesión y activo. Devuelve la imagen en línea como base64 junto con metadatos (formato, dimensiones, tamaño).

Cuando se ejecuta localmente (transporte stdio), opcionalmente puedes proporcionar un destinationPath para guardar la imagen en disco. En el transporte alojado/HTTP, la ruta se ignora y la imagen se devuelve solo en línea.

Ejemplos:

// Inline only (works everywhere)
exportImageAsset({
  sessionId: "uuid-from-generate",
  assetId: "uuid-from-generate"
})

// Save to disk (stdio/local only)
exportImageAsset({
  sessionId: "uuid-from-generate",
  assetId: "uuid-from-generate",
  destinationPath: "/Users/me/project/images/hero.png"
})

Flujos de trabajo guiados (indicaciones)

Además de las herramientas, el servidor expone indicaciones con nombre — flujos de trabajo preconstruidos de múltiples pasos que los clientes MCP pueden mostrar directamente a los usuarios (p. ej. como comandos de barra) o que los agentes pueden invocar por nombre para obtener un resultado más confiable que la llamada libre a herramientas.

Nombre de la indicación	Qué hace
`analyze-webpage`	Obtiene los metadatos de una página y su contenido legible en paralelo, luego resume o responde una pregunta específica sobre ella.
`extract-structured-data`	Extrae campos nombrados (título, precio, SKU, etc.) de una página usando selectores CSS — ideal para comercio electrónico, listados de empleo y artículos.
`get-page-content`	Convierte una URL a texto/Markdown limpio y legible, eliminando contenido repetitivo — listo para leer o pasar a otro modelo.
`run-site-audit`	Flujo de trabajo completo de auditoría de sitio: pregunta al usuario su alcance preferido (sitio completo / páginas principales / sección específica / escaneo del código base), descubre URLs si es necesario, inicia la auditoría, consulta el estado y devuelve un informe legible. Requiere OAuth.
`create-branded-diagram`	Flujo de trabajo guiado para crear diagramas (flujo, secuencia, arquitectura, ER, estado) que coincidan con la identidad de tu marca.
`iterate-and-refine`	Mejores prácticas para iterar sobre una imagen generada previamente para alcanzar el resultado deseado.
`create-asset-set`	Genera un conjunto de iconos, tarjetas sociales, diagramas o ilustraciones visualmente consistentes.
`quick-icon`	Genera rápidamente un solo icono con valores predeterminados sensatos.

Cómo funciona

og-mcp Architecture Diagram ^{Diagrama generado con las herramientas de generación de imágenes de og-mcp}

El servidor og-mcp actúa como un puente entre clientes de IA (como Claude u otros LLM) y la API de OpenGraph.io:

El cliente de IA realiza una llamada a una de las funciones MCP disponibles
El servidor og-mcp recibe la solicitud y la formatea para la API de OpenGraph.io
OpenGraph.io procesa la solicitud y devuelve los datos
og-mcp transforma la respuesta en un formato adecuado para el cliente de IA
El cliente de IA recibe los datos estructurados listos para usar

Esta abstracción evita exponer las claves de API directamente a la IA, al tiempo que proporciona acceso completo a las capacidades de OpenGraph.io.

Configuración y ejecución

Clona este repositorio
Instala las dependencias:
```
npm install
```
Compila el código TypeScript:
```
npm run build
```
Inicia el servidor:
```
npm start
```

El servidor se ejecutará en el puerto 3010 por defecto (configurable mediante la variable de entorno PORT).

Configuración

OAuth 2.1 (servidor HTTP alojado)

Al ejecutar el servidor HTTP Streamable (npm start), establece estas variables de entorno:

# Required: URL of the apifur-api JWKS endpoint
OAUTH_JWKS_URL=https://dashboard-api.opengraph.io/oauth/jwks.json

# Optional: Issuer string to validate in bearer tokens (defaults to OAUTH_ISSUER)
OAUTH_ISSUER=https://dashboard-api.opengraph.io

# Optional: Expected audience claim (default: https://mcp.opengraph.io/mcp)
OAUTH_AUDIENCE=https://mcp.opengraph.io/mcp

# Optional: Override the canonical MCP resource URL returned in 401 headers
MCP_RESOURCE_URL=https://mcp.opengraph.io/mcp

Cuando OAUTH_JWKS_URL no está configurado, la verificación del token de portador está deshabilitada y solo está activo el respaldo de x-app-id.

Respaldo x-app-id / desarrollo local

Omite las variables de entorno de OAuth y usa un ID de aplicación estático en su lugar:

OPENGRAPH_APP_ID=your_app_id_here
# or
APP_ID=your_app_id_here

Esto también funciona como respaldo para cualquier solicitud HTTP que incluya un encabezado x-app-id.

Transporte Stdio

Para uso desde línea de comandos, pasa el ID de aplicación directamente:

opengraph-io-mcp --app-id YOUR_APP_ID

Opciones de transporte

Transporte Stdio (Recomendado)

Para uso desde línea de comandos e instalación global de npm, el servidor se puede ejecutar con transporte stdio:

npm run start:stdio

Puedes pasar la clave de API de OpenGraph directamente mediante un argumento de línea de comandos:

npm run start:stdio -- --app-id YOUR_APP_ID

Cuando se instala globalmente:

opengraph-io-mcp --app-id YOUR_APP_ID

Este modo permite que el servidor sea invocado directamente por otras aplicaciones que usan MCP.

Transporte HTTP/SSE

Este método ejecuta un servidor web al que se puede acceder mediante HTTP y utiliza SSE para la transmisión:

npm start

Solución de problemas

Si las herramientas no aparecen, verifica que el servidor esté ejecutándose y que la URL esté configurada correctamente en Cursor
Revisa los registros del servidor para detectar problemas de conexión o autorización
Verifica que Claude haya recibido instrucciones de usar las herramientas específicas por nombre