Opengraph.io

Dados Opengraph, web scraping, recursos de captura de tela em uma prática ferramenta MCP

Documentação

Servidor MCP OpenGraph (og-mcp)

og‑mcp é um servidor Model‑Context‑Protocol (MCP) que disponibiliza todos os endpoints da API OpenGraph.io ( https://opengraph.io ) para agentes de IA (ex.: Anthropic Claude, Cursor, LangGraph) através da interface padrão do MCP.

Por quê? Se você já usa OpenGraph.io para desdobrar links, extrair HTML, extrair texto de artigos ou capturar screenshots, agora você pode dar as mesmas capacidades aos seus agentes autônomos sem expor chaves de API brutas.

Instalação Global

Você pode instalar este pacote globalmente via npm:

npm install -g opengraph-io-mcp

Instalação Rápida

Instalador via CLI (Recomendado)

A maneira mais fácil de configurar o OpenGraph MCP para qualquer cliente suportado:

# 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 suportados: cursor, claude-desktop, windsurf, vscode, zed, jetbrains

Extensão Claude Desktop

Para usuários do Claude Desktop, você também pode baixar a extensão .mcpb para instalação com um clique na página de Releases.

Autenticação

O servidor MCP hospedado suporta dois métodos de autenticação:

Opção 1 — OAuth 2.1 (recomendado para implantações hospedadas)

O OAuth permite que você autorize o acesso através do seu painel OpenGraph.io sem copiar chaves de API para arquivos de configuração. O cliente MCP lida com todo o fluxo de login no navegador automaticamente.

Suportado por: clientes MCP que implementam o fluxo Authorization Code + PKCE (Cursor, Claude Desktop 0.10+, VS Code com a extensão MCP).

Quando o cliente conecta sem credenciais, o servidor retorna 401 com um cabeçalho WWW-Authenticate apontando para:

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

O cliente então busca os metadados do servidor de autorização e inicia o fluxo PKCE, redirecionando seu navegador para https://dashboard.opengraph.io/oauth/consent onde você faz login e escolhe qual chave de API autorizar.

Nenhuma configuração no lado do cliente necessária — o cliente descobre tudo automaticamente.

Opção 2 — Cabeçalho `x-app-id` (legado / desenvolvimento local)

Passe seu App ID como um cabeçalho HTTP. Adequado para desenvolvimento local, CI ou clientes que não suportam OAuth.

Substitua YOUR_OPENGRAPH_APP_ID pelo seu OpenGraph.io App ID.

Configuração do Cliente

Todas as configurações abaixo usam o transporte HTTPS hospedado. OAuth é a abordagem recomendada para uso compartilhado/produção; a configuração do cabeçalho x-app-id é fornecida como alternativa.

OAuth (nenhuma configuração estática necessária)

Para clientes que suportam descoberta OAuth, basta apontar para a URL hospedada sem cabeçalhos — o servidor solicitará autorização automaticamente:

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

Alternativa x-app-id

Se o seu cliente não suporta OAuth, ou se você prefere configuração estática:

Claude Desktop

Local da configuração:

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

Instalação com um comando:

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

Cursor

Local da configuração: ~/.cursor/mcp.json

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

VS Code

Local da configuração: .vscode/mcp.json (no diretório do seu projeto)

O VS Code suporta prompts de entrada para tratamento seguro de credenciais:

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

Local da configuração: ~/.codeium/windsurf/mcp_config.json

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

JetBrains AI Assistant

Adicione à sua configuração MCP do JetBrains AI Assistant:

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

Zed

Local da configuração: ~/.config/zed/settings.json

Nota: Zed usa context_servers em vez de mcpServers:

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

Ferramentas Disponíveis

Dois níveis de autenticação: As ferramentas de Dados e Geração de Imagem funcionam com OAuth ou com uma chave de API simples x-app-id — incluindo o transporte stdio e a extensão Claude Desktop. As ferramentas de Auditoria de Site e Pré-visualização de Link exigem OAuth (somente transporte HTTPS hospedado), pois são cobradas no plano de Auditoria de Site da sua organização, e não em uma única chave de API.

Ferramentas de Dados OpenGraph.io

Todas as ferramentas de scraping/metadados usam por padrão a API v3, que habilita auto_render, auto_proxy e retry por padrão para maiores taxas de sucesso em páginas complexas. As ferramentas query e extract usam v1.1 (veja notas).

Nome da Ferramenta	Endpoint da API	Descrição	Documentação
Obter Dados OG	`/api/3.0/site/<URL>`	Busca metadados Open Graph, tags inferidas de HTML e dados de pré-visualização social híbridos. Suporta `use_ai`, `ai_sanitize`, carregar-mais, proxy/repetição e todos os padrões inteligentes v3.	Docs
Obter Dados de Scrape OG	`/api/3.0/scrape/<URL>`	Extrai HTML bruto com opções completas de renderização v3, incluindo rolar até o fim, cliques em carregar-mais e sanitização por IA.	Docs
Obter Screenshot OG	`/api/3.0/screenshot/<URL>`	Captura um screenshot. Suporta `full_page`, `dark_mode`, `capture_delay`, `navigationTimeout`, `hideSelectors` e dimensões personalizadas de viewport.	Docs
Obter Consulta OG	`/api/1.1/query/<URL>`	Faz uma pergunta em linguagem natural sobre o conteúdo de uma página. Usa v1.1 (100–200 créditos/requisição) até que o caminho de cobrança seja atualizado para v3.	Docs
Obter Extração OG	`/api/1.1/extract/<URL>`	Extrai elementos HTML específicos (h1, p, a, img, etc.) por nome de tag. Permanece na v1.1 — não existe rota GET v3 para este endpoint.	Docs
Obter Markdown OG	`/api/3.0/markdown/<URL>`	Converte o HTML de qualquer URL em Markdown limpo. Remove nav/anúncios por padrão (`only_main_content: true`). Suporta seletores `include_tags`/`exclude_tags`. Nota: Páginas com muito JS/SPA exigem `full_render: true` — o `auto_render` v3 não se aplica a este endpoint.	Docs

Detecção de idioma: Todas as ferramentas enviam accept_lang: auto por padrão, que espelha o cabeçalho Accept-Language da requisição. Passe uma tag BCP 47 explícita (ex.: en-US, fr) para substituir.

Ferramentas de Auditoria de Site e Pré-visualização de Link

Exige OAuth 2.1 (veja Autenticação) e um plano ativo de Auditoria de Site. Essas ferramentas estão disponíveis apenas no transporte HTTPS hospedado — não estão disponíveis via cabeçalho x-app-id ou na extensão stdio/Claude Desktop, pois precisam da identidade da sua organização, não apenas de uma chave de API.

Nome da Ferramenta	Descrição
Descobrir URLs do Site	Rastreia um domínio (sitemap + descoberta de links) e retorna todas as páginas encontradas, agrupadas por profundidade, junto com sua cota mensal restante de auditoria.
Iniciar Auditoria do Site	Inicia uma auditoria assíncrona de SEO/social em várias páginas. Passe uma lista explícita de `urls[]` (da descoberta, de um sitemap ou de uma varredura de rotas do código) ou deixe o backend rastrear o domínio sozinho. Retorna um `auditId` imediatamente.
Obter Status da Auditoria do Site	Consulta uma auditoria em andamento (`QUEUED` → `CRAWLING` → `SCORING` → `COMPLETE`).
Obter Relatório da Auditoria do Site	Recupera o relatório completo quando concluído: pontuação geral (0–100), um resumo executivo gerado por IA, correções priorizadas, pontuações por página e taxas de cobertura Open Graph.
Pré-visualizar Auditoria de Página	Verificação instantânea e síncrona de qualidade de URL única com pontuação e problemas. Não consome cota de auditoria.
Obter Pré-visualização de Link	Verificação instantânea e síncrona de como uma URL será renderizada ao ser compartilhada — retorna cartões de pré-visualização do Facebook, Twitter/X, LinkedIn e Google, além de uma pontuação de qualidade e lista de correções. Não consome cota de auditoria.

Ferramentas de Geração de Imagem

Nome da Ferramenta	Descrição
Gerar Imagem	Cria imagens profissionais: ilustrações, diagramas (Mermaid/D2/Vega), ícones, cartões sociais ou códigos QR
Iterar Imagem	Refina, modifica ou cria variações de imagens geradas existentes
Inspecionar Sessão de Imagem	Recupera metadados da sessão e histórico de ativos para sessões de geração de imagem
Exportar Ativo de Imagem	Exporta ativos de imagem gerados como base64 inline, com opção de gravação em disco quando executado localmente

Geração de Imagem

O servidor og-mcp inclui poderosas capacidades de geração de imagem orientadas por IA, perfeitas para criar cartões de mídia social, diagramas de arquitetura, ícones e muito mais.

Gerar Imagem

Cria imagens a partir de prompts em linguagem natural ou código de diagrama.

Tipos de Imagem Suportados (kind):

illustration - Imagens geradas por IA de uso geral
diagram - Diagramas técnicos a partir de sintaxe Mermaid, D2 ou Vega
icon - Ícones de aplicativos e logotipos
social-card - Imagens OG otimizadas para compartilhamento social
qr-code - Códigos QR com estilização opcional

Proporções de Aspecto Predefinidas:

Social: og-image, twitter-card, twitter-post, linkedin-post, facebook-post, instagram-square, instagram-portrait, instagram-story, youtube-thumbnail
Padrão: wide, square, portrait
Ícones: icon-small, icon-medium, icon-large

Predefinições de Estilo: github-dark, github-light, notion, vercel, linear, stripe, neon-cyber, pastel, minimal-mono, corporate, startup, documentation, technical

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

Exemplo 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 Imagem

Refina ou modifica uma imagem gerada existente.

Casos de uso:

Editar partes específicas: "mude o fundo para azul"
Aplicar mudanças de estilo: "deixe mais minimalista"
Corrigir problemas: "remova o texto", "deixe o ícone maior"
Recortar para coordenadas específicas

Exemplo:

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

Inspecionar Sessão de Imagem

Revisa detalhes da sessão e encontra IDs de ativos para iteração.

Retorna:

Metadados da sessão (hora de criação, nome, status)
Lista de todos os ativos com prompts, toolchains e status
Relações pai-filho mostrando o histórico de iteração

Exemplo:

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

Exportar Ativo de Imagem

Exporta um ativo de imagem gerado por ID de sessão e ativo. Retorna a imagem inline como base64 junto com metadados (formato, dimensões, tamanho).

Ao executar localmente (transporte stdio), você pode opcionalmente fornecer um destinationPath para salvar a imagem em disco. No transporte hospedado/HTTP, o caminho é ignorado e a imagem é retornada apenas inline.

Exemplos:

// 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"
})

Fluxos de Trabalho Guiados (Prompts)

Além das ferramentas, o servidor expõe prompts nomeados — fluxos de trabalho pré-construídos em várias etapas que os clientes MCP podem apresentar diretamente aos usuários (ex.: como comandos de barra) ou que os agentes podem invocar pelo nome para um resultado mais confiável do que chamadas de ferramentas livres.

Nome do Prompt	O que faz
`analyze-webpage`	Busca os metadados e o conteúdo legível de uma página em paralelo, depois resume ou responde a uma pergunta específica sobre ela.
`extract-structured-data`	Extrai campos nomeados (título, preço, SKU, etc.) de uma página usando seletores CSS — ideal para ecommerce, listas de empregos e artigos.
`get-page-content`	Converte uma URL em texto/Markdown limpo e legível, removendo conteúdo repetitivo — pronto para ler ou passar para outro modelo.
`run-site-audit`	Fluxo de trabalho completo de auditoria de site: pergunta ao usuário o escopo preferido (site inteiro / páginas principais / seção específica / varredura de código), descobre URLs se necessário, inicia a auditoria, consulta o status e retorna um relatório legível. Exige OAuth.
`create-branded-diagram`	Fluxo de trabalho guiado para criar diagramas (fluxograma, sequência, arquitetura, ER, estado) que correspondam à identidade da sua marca.
`iterate-and-refine`	Melhores práticas para iterar em uma imagem gerada anteriormente para alcançar o resultado desejado.
`create-asset-set`	Gera um conjunto visualmente consistente de ícones, cartões sociais, diagramas ou ilustrações.
`quick-icon`	Gera rapidamente um único ícone com padrões sensatos.

Como funciona

og-mcp Architecture Diagram ^{Diagrama gerado com as ferramentas de geração de imagem do og-mcp}

O servidor og-mcp atua como uma ponte entre clientes de IA (como Claude ou outros LLMs) e a API OpenGraph.io:

O cliente de IA faz uma chamada de ferramenta para uma das funções MCP disponíveis
O servidor og-mcp recebe a solicitação e a formata para a API do OpenGraph.io
O OpenGraph.io processa a solicitação e retorna os dados
O og-mcp transforma a resposta em um formato adequado para o cliente de IA
O cliente de IA recebe os dados estruturados prontos para uso

Essa abstração evita expor chaves de API diretamente à IA, ao mesmo tempo em que fornece acesso completo aos recursos do OpenGraph.io.

Configuração e Execução

Clone este repositório
Instale as dependências:
```
npm install
```
Compile o código TypeScript:
```
npm run build
```
Inicie o servidor:
```
npm start
```

O servidor será executado na porta 3010 por padrão (configurável por meio da variável de ambiente PORT).

Configuração

OAuth 2.1 (servidor HTTP hospedado)

Ao executar o servidor HTTP Streamable (npm start), defina estas variáveis de ambiente:

# 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

Quando OAUTH_JWKS_URL não estiver definido, a verificação do token de portador é desativada e apenas o fallback x-app-id fica ativo.

Fallback x-app-id / desenvolvimento local

Omita as variáveis de ambiente OAuth e use um ID de aplicativo estático:

OPENGRAPH_APP_ID=your_app_id_here
# or
APP_ID=your_app_id_here

Isso também funciona como fallback para qualquer solicitação HTTP que inclua um cabeçalho x-app-id.

Transporte Stdio

Para uso em linha de comando, passe o ID do aplicativo diretamente:

opengraph-io-mcp --app-id YOUR_APP_ID

Opções de Transporte

Transporte Stdio (Recomendado)

Para uso em linha de comando e instalação global via npm, o servidor pode ser executado com transporte stdio:

npm run start:stdio

Você pode passar a chave da API OpenGraph diretamente por argumento de linha de comando:

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

Quando instalado globalmente:

opengraph-io-mcp --app-id YOUR_APP_ID

Este modo permite que o servidor seja invocado diretamente por outros aplicativos que usam MCP.

Transporte HTTP/SSE

Este método executa um servidor web que pode ser acessado via HTTP e usa SSE para streaming:

npm start

Solução de Problemas

Se as ferramentas não aparecerem, verifique se o servidor está em execução e se a URL está configurada corretamente no Cursor
Verifique os logs do servidor para quaisquer problemas de conexão ou autorização
Confirme se o Claude foi instruído a usar as ferramentas específicas pelo nome