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) por meio da interface padrão do MCP.

Por quê? Se você já usa OpenGraph.io para desfazer links, extrair HTML, extrair texto de artigos ou capturar capturas de tela, 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 compatível:

# 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 compatíveis: 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 por meio do painel do 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.

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

Quando o cliente se 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 App ID do OpenGraph.io.

Configuração do Cliente

Todas as configurações abaixo usam o transporte HTTPS hospedado. O 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ê preferir 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 à configuração MCP do seu 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

Observação: o 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 as 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 rolagem até o final, cliques em "carregar mais" e sanitização por IA.	Docs
Obter Captura de Tela OG	`/api/3.0/screenshot/<URL>`	Captura uma captura de tela. 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/solicitaçã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`) e suporta seletores `include_tags`/`exclude_tags`. Para páginas longas, passe `query` com `chunking` para obter apenas as passagens relevantes, classificadas, em vez do documento inteiro. `include_links`/`include_images`/`include_headings` retornam dados estruturados de links, imagens e estrutura. Retorna metadados da página, uso de caracteres e tokens e — com `ai_sanitize` — um relatório de segurança contra injeção de prompt.	Docs

Detecção de idioma: Todas as ferramentas enviam accept_lang: auto por padrão, que espelha o cabeçalho Accept-Language da solicitaçã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

Requer 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 de 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 de Site	Consulta uma auditoria em andamento (`QUEUED` → `CRAWLING` → `SCORING` → `COMPLETE`).
Obter Relatório de Auditoria de 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.
Excluir Auditoria de Site	Exclui permanentemente uma auditoria e todos os seus resultados. Não pode ser desfeito.

Ferramentas de Monitoramento e Histórico

Auditorias recorrentes, acompanhamento de tendências e relatórios de alterações. OAuth necessário; setMonitoringSchedule adicionalmente requer o direito de agendamento de Auditoria de Site.

Nome da Ferramenta	Descrição
Listar Sites	Cada site que a organização auditou, com pontuação atual e tendência em relação à execução anterior, contagens de problemas críticos e regressões, contagem conhecida de páginas e próxima execução agendada. Passe um `websiteId` para obter um em detalhes.
Listar Auditorias de Site	Auditorias passadas, mais recentes primeiro, filtráveis por domínio, status, intervalo de datas ou site.
Obter Alterações da Auditoria de Site	O que mudou desde a execução anterior — problemas novos, corrigidos e regredidos, páginas adicionadas ou removidas e o delta de pontuação — além de grupos de problemas priorizados. Um problema regredido é aquele anteriormente verificado como corrigido que voltou; isso é rastreado entre execuções por identidade durável do problema, não pela comparação de duas listas.
Obter Agendamento de Monitoramento	Configurações de auditoria recorrente de um site: frequência, dia e hora ancorados, estado de pausa, próxima execução.
Definir Agendamento de Monitoramento	Ativa, altera ou remove auditorias recorrentes. Compromete gasto contínuo de cota de páginas e pode disparar e-mail de alerta. `enabled: false` exclui a configuração — use `paused: true` para mantê-la. Os destinatários de alertas são apenas do painel.
Obter Contexto de Conexão	Qual organização esta conexão representa e quais recursos de Auditoria de Site seu plano permite. A organização é escolhida durante a autorização e é o padrão para todas as ferramentas.

Ferramentas de Lista de Correções

Transforme uma auditoria em trabalho que um desenvolvedor possa executar. OAuth necessário.

Nome da Ferramenta	Descrição
Listar Itens de Correção	Alterações de metadados propostas e notas salvas em uma auditoria, agrupadas por página, cada uma com um ID.
Salvar Itens de Correção	Registra alterações propostas para uma página. Substitui itens existentes para a mesma página e campo. Um `proposedValue` em branco ou inalterado é rejeitado — significa "remover" no sistema, então use Excluir Item de Correção deliberadamente.
Excluir Item de Correção	Remove permanentemente uma entrada. Os itens de correção são escritos manualmente e não são regenerados por re-auditoria.
Exportar Itens de Correção CSV	A lista de correções como texto CSV para transferência. A exportação em PDF está disponível apenas no painel.
Enviar Relatório de Auditoria de Site por E-mail	Envia o relatório por e-mail com anexos em PDF para o endereço da própria conta autenticada. Envia e-mail real em cada chamada e não é idempotente; o destinatário não pode ser escolhido.

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

Crie 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 e logotipos de aplicativos
social-card - Imagens OG otimizadas para compartilhamento social
qr-code - Códigos QR com estilização opcional

Proporções de Tela 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

Refine ou modifique 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

Revise os detalhes da sessão e encontre 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

Exporte um ativo de imagem gerado por sessão e ID de 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 exibir diretamente aos usuários (por exemplo, como comandos de barra) ou que agentes podem invocar pelo nome para obter um resultado mais confiável do que chamadas de ferramentas livres.

Nome do Prompt	O que faz
`analyze-webpage`	Busca os metadados de uma página e o conteúdo legível 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 e-commerce, listas de empregos e artigos.
`get-page-content`	Converte uma URL em texto/Markdown limpo e legível, removendo conteúdo redundante — 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, verifica o status e retorna um relatório legível. Requer 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 do 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, enquanto fornece acesso total 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 pela variável de ambiente PORT).

Configuração

OAuth 2.1 (servidor HTTP hospedado)

Ao executar o servidor Streamable HTTP (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 via 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 Streamable

Este método executa um servidor web que pode ser acessado via HTTP:

npm start

O transporte SSE legado (/sse + /message) foi removido. Ele não tinha autenticação e compartilhava uma única conexão entre todos os clientes.

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
Verifique se o Claude foi instruído a usar as ferramentas específicas pelo nome