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 (por ejemplo, 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 App como un encabezado HTTP. Adecuado para desarrollo local, CI o clientes que no admiten OAuth.

Reemplaza YOUR_OPENGRAPH_APP_ID con tu ID de App 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 — incluyendo 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, incluyendo desplazamiento hasta el fondo, 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`) y admite selectores `include_tags`/`exclude_tags`. Para páginas largas, pasa `query` con `chunking` para obtener solo los pasajes relevantes, clasificados, en lugar de todo el documento. `include_links`/`include_images`/`include_headings` devuelven datos estructurados de enlaces, imágenes y esquema. Devuelve metadatos de página, uso de caracteres y tokens, y — con `ai_sanitize` — un informe de seguridad contra inyección de prompts.	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 (por ejemplo, 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 mensual restante de auditoría.
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[]` (de 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 progreso (`QUEUED` → `CRAWLING` → `SCORING` → `COMPLETE`).
Obtener Informe de Auditoría de Sitio	Recupera el informe completo una vez completado: 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 de calidad 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.
Eliminar Auditoría de Sitio	Elimina permanentemente una auditoría y todos sus resultados. No se puede deshacer.

Herramientas de Monitoreo e Historial

Auditorías recurrentes, seguimiento de tendencias e informes de cambios. Se requiere OAuth; setMonitoringSchedule además requiere el derecho de programación de Auditoría de Sitio.

Nombre de la Herramienta	Descripción
Listar Sitios Web	Cada sitio que la organización ha auditado, con puntuación actual y tendencia contra la ejecución anterior, recuentos de problemas críticos y regresiones, recuento de páginas conocidas y próxima ejecución programada. Pasa un `websiteId` para uno en detalle.
Listar Auditorías de Sitio	Auditorías pasadas, más recientes primero, filtrables por dominio, estado, rango de fechas o sitio web.
Obtener Cambios de Auditoría de Sitio	Qué cambió desde la ejecución anterior — problemas nuevos, corregidos y con regresión, páginas agregadas o eliminadas, y el delta de puntuación — además de grupos de problemas priorizados. Un problema con regresión es uno previamente verificado como corregido que ha vuelto; esto se rastrea entre ejecuciones por identidad de problema duradera, no comparando dos listas.
Obtener Programa de Monitoreo	Configuración de auditoría recurrente de un sitio web: frecuencia, día y hora anclados, estado de pausa, próxima ejecución.
Establecer Programa de Monitoreo	Habilita, cambia o elimina auditorías recurrentes. Compromete gasto de cuota de páginas en curso y puede activar correos de alerta. `enabled: false` elimina la configuración — usa `paused: true` para mantenerla. Los destinatarios de alertas son solo del panel.
Obtener Contexto de Conexión	Qué organización representa esta conexión y qué funciones de Auditoría de Sitio permite su plan. La organización se elige durante la autorización y es a la que todas las herramientas se dirigen por defecto.

Herramientas de Lista de Correcciones

Convierte una auditoría en trabajo que un desarrollador pueda ejecutar. Se requiere OAuth.

Nombre de la Herramienta	Descripción
Listar Elementos de Corrección	Cambios de metadatos propuestos y notas guardadas contra una auditoría, agrupados por página, cada uno con un ID.
Guardar Elementos de Corrección	Registra cambios propuestos para una página. Sobrescribe elementos existentes para la misma página y campo. Un `proposedValue` en blanco o sin cambios es rechazado — significa "eliminar" en el sistema, así que usa Eliminar Elemento de Corrección deliberadamente.
Eliminar Elemento de Corrección	Elimina permanentemente una entrada. Los elementos de corrección son escritos a mano y no se regeneran al re-auditar.
Exportar CSV de Elementos de Corrección	La lista de correcciones como texto CSV para entrega. La exportación PDF está disponible solo en el panel.
Enviar Informe de Auditoría de Sitio por Correo	Envía el informe por correo con archivos PDF adjuntos a la dirección del propio usuario autenticado. Envía un correo real en cada llamada y no es idempotente; el destinatario no se puede elegir.

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 prompts en lenguaje natural o código de diagramas.

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 de aplicaciones y logotipos
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

Preestablecidos de Estilo: 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 los IDs de activos para iterar.

Devuelve:

Metadatos de la sesión (tiempo de creación, nombre, estado)
Lista de todos los activos con prompts, toolchains 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 sesión e ID de 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 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 (Prompts)

Además de las herramientas, el servidor expone prompts con nombre — flujos de trabajo preconstruidos de varios pasos que los clientes MCP pueden mostrar directamente a los usuarios (por ejemplo, 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 del Prompt	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 con nombre (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 el 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 de código), 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 tu identidad de marca.
`iterate-and-refine`	Mejores prácticas para iterar sobre una imagen generada previamente y alcanzar el resultado deseado.
`create-asset-set`	Genera un conjunto visualmente consistente de iconos, tarjetas sociales, diagramas o ilustraciones.
`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 los clientes de IA (como Claude u otros LLMs) 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 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 mientras 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)

Cuando se ejecuta el servidor Streamable HTTP (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 el respaldo x-app-id está activo.

Respaldo x-app-id / desarrollo local

Omite las variables de entorno OAuth y usa un ID de App 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 App 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 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 Streamable

Este método ejecuta un servidor web al que se puede acceder a través de HTTP:

npm start

El transporte SSE heredado (/sse + /message) ha sido eliminado. No tenía autenticación y compartía una sola conexión entre todos los clientes.

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 sido instruido para usar las herramientas específicas por nombre