Opengraph.io

OpenGraph MCP 服务

opengraph-io-mcp 是一个模型上下文协议（MCP）服务，可通过标准 MCP 接口，让 Claude、Cursor 和 LangGraph 等 AI Agent 使用 OpenGraph.io API。

为什么需要它？如果你已经使用 OpenGraph.io 展开链接、抓取 HTML、提取文章文本或截取屏幕截图，现在可以让自主 Agent 使用相同的功能，而无需暴露原始 API 密钥。

全局安装

你可以通过 npm 全局安装此软件包：

npm install -g opengraph-io-mcp

快速安装

CLI 安装程序（推荐）

为任何受支持的客户端配置 OpenGraph MCP 的最简单方式：

# 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

支持的客户端：cursor、claude-desktop、windsurf、vscode、zed、jetbrains

Claude Desktop 扩展

对于 Claude Desktop，请从 Releases 页面下载 .mcpb 扩展并打开。Claude Desktop 会要求你输入一次 App ID，并将其安全保存。

身份验证

托管服务 https://mcp.opengraph.io/mcp 使用 OAuth 2.1。你只需在浏览器中登录一次，并选择要授权的 OpenGraph.io API 密钥；配置文件中不会保存任何机密信息，你也可以随时从控制面板撤销访问权限。OAuth 还会解锁 Open Graph Audit 和 Link Preview 工具。

工作原理：客户端在没有凭据的情况下连接时，服务会返回带有 WWW-Authenticate 标头的 401，其中指向

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

客户端会从那里发现授权服务，并在浏览器中打开 https://dashboard.opengraph.io/oauth/consent。支持内置 OAuth 的客户端只需要 URL。只能启动本地命令的客户端则通过 mcp-remote 连接；这是一个在你的计算机上运行的小型桥接程序，负责处理相同的浏览器登录流程。

托管服务上的 x-app-id 标头已弃用。 目前仍可使用该标头，并且响应中会包含 Deprecation 标头，但我们正在移除对它的支持。请改用以下某种 OAuth 配置。在本地运行服务（stdio 传输、CLI 安装程序或 Claude Desktop 扩展）时会直接使用你的 App ID，不受影响。

---

客户端配置

以下每种配置都会通过 OAuth 连接到托管服务。首次使用工具时，浏览器会打开供你登录。

Claude Code

claude mcp add --transport http opengraph https://mcp.opengraph.io/mcp

然后在 Claude Code 中运行 /mcp，并选择 opengraph 登录。

Claude Desktop

设置 → 连接器 → 添加自定义连接器，将其命名为 OpenGraph，然后输入 https://mcp.opengraph.io/mcp。Claude Desktop 会在浏览器中打开登录页面。

如果你更喜欢使用配置文件（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上的 %APPDATA%\Claude\claude_desktop_config.json），请使用 mcp-remote 桥接程序：

{
  "mcpServers": {
    "opengraph": {
      "command": "npx",
      "args": ["-y", "[email protected]", "https://mcp.opengraph.io/mcp"]
    }
  }
}

Cursor

从 Cursor Marketplace 安装 OpenGraph.io 插件，或自行添加服务。

配置位置：~/.cursor/mcp.json

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

VS Code

配置位置：.vscode/mcp.json（位于项目目录中）

{
  "servers": {
    "opengraph": {
      "type": "http",
      "url": "https://mcp.opengraph.io/mcp"
    }
  }
}

Windsurf、JetBrains AI Assistant、Zed 和其他客户端

如果你的客户端支持远程服务的 OAuth，请将其指向 https://mcp.opengraph.io/mcp，且不带任何标头。否则，请通过 mcp-remote 连接：

Windsurf（~/.codeium/windsurf/mcp_config.json）和 JetBrains AI Assistant：

{
  "mcpServers": {
    "opengraph": {
      "command": "npx",
      "args": ["-y", "[email protected]", "https://mcp.opengraph.io/mcp"]
    }
  }
}

Zed（~/.config/zed/settings.json，使用 context_servers）：

{
  "context_servers": {
    "opengraph": {
      "command": "npx",
      "args": ["-y", "[email protected]", "https://mcp.opengraph.io/mcp"]
    }
  }
}

mcp-remote 会将登录信息存储在 ~/.mcp-auth 中。删除该文件夹即可退出登录。

旧版 x-app-id 标头（已弃用）

仅适用于暂时无法使用 OAuth 的配置，且仅在托管服务仍接受该标头时使用。将你的 OpenGraph.io App ID 作为标头发送；此方式无法使用 Open Graph Audit 和 Link Preview 工具。

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

可用工具

两个身份验证层级： 数据和图像生成工具支持 OAuth；在本地运行服务（使用 stdio 传输或 Claude Desktop 扩展）时，也支持使用普通 App ID。托管服务上的 Open Graph Audit 和 Link Preview 工具需要 OAuth，因为费用会计入你所在组织的套餐，而非单个 API 密钥。

OpenGraph.io 数据工具

所有抓取／元数据工具默认使用 v3 API，默认启用 auto_render、auto_proxy 和 retry，以提高复杂网页的成功率。query 和 extract 工具使用 v1.1（请参阅说明）。

工具名称	API 端点	描述	文档
Get OG Data	/api/3.0/site/<URL>	获取 Open Graph 元数据、从 HTML 推断的标签以及混合社交预览数据。支持 use_ai、ai_sanitize、加载更多、代理／重试以及所有 v3 智能默认选项。	文档
Get OG Scrape Data	/api/3.0/scrape/<URL>	抓取原始 HTML，支持完整的 v3 渲染选项，包括滚动到底部、点击加载更多和 AI 清理。	文档
Get OG Screenshot	/api/3.0/screenshot/<URL>	截取屏幕截图。支持 full_page、dark_mode、capture_delay、navigationTimeout、hideSelectors 和自定义视口尺寸。	文档
Get OG Query	/api/1.1/query/<URL>	使用自然语言询问有关网页内容的问题。在 v3 计费路径更新前，使用 v1.1（每次请求 100–200 个 credits）。	文档
Get OG Extract	/api/1.1/extract/<URL>	按标签名提取特定 HTML 元素（h1、p、a、img 等）。继续使用 v1.1——此端点不存在 v3 GET 路由。	文档
Get OG Markdown	/api/3.0/markdown/<URL>	将任意 URL 的 HTML 转换为干净的 Markdown。默认移除导航栏／广告（only_main_content: true），并支持 include_tags／exclude_tags 选择器。对于较长的网页，传入 query 和 chunking，即可仅获取相关段落（按相关性排序），而非整个文档。include_links／include_images／include_headings 会返回结构化的链接、图片和大纲数据。返回网页元数据、字符和 token 用量；启用 ai_sanitize 时，还会返回提示词注入安全报告。	文档

语言检测： 所有工具默认发送 accept_lang: auto，与请求的 Accept-Language 标头保持一致。传入明确的 BCP 47 标签（例如 en-US、fr）即可覆盖此设置。

Open Graph 审计与链接预览工具

需要 OAuth 2.1（参见身份验证）以及包含 Open Graph 审计的套餐。这些工具仅在托管服务上提供。在本地运行服务（使用 CLI 安装程序或 Claude Desktop 扩展）或通过 x-app-id 标头连接时，不会列出这些工具，因为它们需要组织身份，而不仅仅是 API 密钥。

工具名称	描述
发现网站 URL	抓取域名（站点地图 + 链接发现），返回找到的所有页面，按深度分组，并附上每月剩余审计配额。
启动 Open Graph 审计	启动异步、多页面的 SEO/社交审计。传入明确的 urls[] 列表（来自发现结果、站点地图或代码库路由扫描），也可以让后端自行抓取域名。立即返回 auditId。
获取 Open Graph 审计状态	轮询进行中的审计（QUEUED → CRAWLING → SCORING → COMPLETE）。
获取 Open Graph 审计报告	审计完成后获取完整报告：总体评分（0–100）、AI 生成的执行摘要、按优先级排列的修复建议、各页面评分以及 Open Graph 覆盖率。
预览页面审计	即时、同步地检查单个 URL 的质量，并返回评分和问题。不会消耗审计配额。
获取链接预览	即时、同步地检查分享 URL 时的呈现效果——返回 Facebook、Twitter/X、LinkedIn 和 Google 的预览卡片，以及质量评分和修复列表。不会消耗审计配额。
删除 Open Graph 审计	永久删除审计及其所有结果。此操作无法撤销。

监控与历史记录工具

定期审计、趋势跟踪和变更报告。需要 OAuth；setMonitoringSchedule 还需要 Open Graph 审计排期权限。

工具名称	描述
列出网站	组织审计过的所有网站，以及当前评分和相较上次运行的趋势、严重问题和回退问题数量、已知页面数量及下次计划运行时间。传入 websiteId 可查看某个网站的详细信息。
列出 Open Graph 审计	过往审计，按时间从新到旧排列，可按域名、状态、日期范围或网站筛选。
获取 Open Graph 审计变更	查看自上次运行以来的变更——新增、已修复和回退的问题，新增或移除的页面，以及评分变化——并附上按优先级排列的问题分组。回退问题是指先前已确认修复、之后又重新出现的问题；系统会通过持久的问题标识跨运行跟踪，而不是比较两个列表。
获取监控计划	查看网站的定期审计设置：频率、固定的日期和时间、暂停状态以及下次运行时间。
设置监控计划	启用、更改或移除定期审计。将持续消耗页面配额，并可能触发提醒邮件。enabled: false 会删除配置——如需保留配置，请使用 paused: true。提醒收件人只能在控制面板中设置。
获取连接上下文	查看此连接代表哪个组织，以及其套餐允许使用哪些 Open Graph 审计功能。组织在授权期间选定，也是所有工具默认使用的组织。

修复项工具

将审计结果转化为开发者可执行的工作。需要 OAuth。

工具名称	说明
List Fix Items	列出针对审计保存的建议元数据更改和备注，按页面分组，每项均有 ID。
Save Fix Items	记录某个页面的建议更改。覆盖同一页面和字段的现有项。空白或未更改的 proposedValue 会被拒绝——这表示上游的“移除”，因此请有意使用 Delete Fix Item。
Delete Fix Item	永久移除一项。修复项由人工编写，不会通过重新审计重新生成。
Export Fix Items CSV	将修复列表导出为 CSV 文本以便交接。仅仪表板支持 PDF 导出。
Email Open Graph Audit Report	将报告及 PDF 附件发送到已验证账户自己的邮箱地址。每次调用都会发送真实邮件，且操作不可幂等；无法选择收件人。

图像生成工具

工具名称	说明
Generate Image	创建专业图像：插图、图表（Mermaid/D2/Vega）、图标、社交媒体卡片或二维码
Iterate Image	优化、修改或创建现有生成图像的变体
Inspect Image Session	获取图像生成会话的元数据和资源历史记录
Export Image Asset	将生成的图像资源导出为内嵌 base64；在本地运行时可选择写入磁盘

图像生成

该服务包含强大的 AI 驱动图像生成功能，非常适合创建社交媒体卡片、架构图、图标等。

Generate Image

通过自然语言提示词或图表代码创建图像。

支持的图像类型（kind）：

• illustration - 通用 AI 生成图像
• diagram - 使用 Mermaid、D2 或 Vega 语法创建技术图表
• icon - 应用图标和徽标
• social-card - 针对社交分享优化的 OG 图像
• qr-code - 可选择样式的二维码

预设宽高比：

• 社交媒体：og-image、twitter-card、twitter-post、linkedin-post、facebook-post、instagram-square、instagram-portrait、instagram-story、youtube-thumbnail
• 标准：wide、square、portrait
• 图标：icon-small、icon-medium、icon-large

风格预设： github-dark、github-light、notion、vercel、linear、stripe、neon-cyber、pastel、minimal-mono、corporate、startup、documentation、technical

图表模板： auth-flow、oauth2-flow、crud-api、microservices、ci-cd、gitflow、database-schema、state-machine、user-journey、cloud-architecture、system-context

使用示例：

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

Iterate Image

优化或修改现有的生成图像。

使用场景：

• 编辑特定部分：“将背景改成蓝色”
• 应用风格更改：“让它更简约”
• 修复问题：“移除文字”“放大图标”
• 按指定坐标裁剪

示例：

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

Inspect Image Session

查看会话详情并查找用于迭代的资源 ID。

返回内容：

• 会话元数据（创建时间、名称、状态）
• 所有资源的列表，包含提示词、工具链和状态
• 显示迭代历史的父子关系

示例：

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

导出图像资源

按会话和资源 ID 导出生成的图像资源。返回包含元数据（格式、尺寸、大小）的 base64 内嵌图像。

在本地运行时（stdio 传输），你可以选择提供 destinationPath，将图像保存到磁盘。在托管/HTTP 传输中，路径会被忽略，图像仅以内嵌形式返回。

文件只会写入一个导出文件夹：默认为 ~/Downloads/opengraph-mcp，或使用 MCP_EXPORT_DIR 中指定的文件夹。请传入文件名或该文件夹内的路径；任何位于该文件夹之外的路径都会被拒绝，隐藏文件和文件夹也会被拒绝。扩展名必须与图像类型匹配（如果名称没有扩展名，则会自动添加）。由于 SVG 可能包含脚本，因此绝不会以内嵌形式返回 SVG 图像；请改为将其保存到磁盘。

示例：

// 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: "hero.png"   // saved as ~/Downloads/opengraph-mcp/hero.png
})

引导式工作流（提示词）

除了工具之外，服务还提供命名的提示词——预先构建的多步骤工作流，MCP 客户端可以直接呈现给用户（例如作为斜杠命令），Agent 也可以按名称调用，以获得比自由形式工具调用更可靠的结果。

提示词名称	功能说明
analyze-webpage	并行获取网页的元数据和可读内容，然后进行摘要或回答有关该网页的特定问题。
extract-structured-data	使用 CSS 选择器从网页提取指定字段（标题、价格、SKU 等），非常适合电商页面、职位列表和文章。
get-page-content	将 URL 转换为简洁易读的文本/Markdown，去除模板内容，便于阅读或传递给其他模型。
run-site-audit	完整的网站审计工作流：询问用户偏好的范围（整个网站 / 核心页面 / 特定部分 / 代码库扫描），必要时发现 URL，启动审计、轮询状态并返回易读的报告。需要 OAuth。
create-branded-diagram	引导创建符合品牌形象的图表（流程图、时序图、架构图、ER 图、状态图）。
iterate-and-refine	提供迭代已有生成图像并优化结果的最佳实践。
create-asset-set	生成一组视觉风格一致的图标、社交卡片、图表或插画。
quick-icon	使用合理的默认设置快速生成单个图标。

工作原理

^{使用此服务的图像生成工具生成的图表}

该服务充当 AI 客户端（如 Claude 或其他大模型）与 OpenGraph.io API 之间的桥梁：

1. AI 客户端向一个可用的 MCP 函数发起工具调用
2. 服务接收请求，并将其转换为 OpenGraph.io API 所需的格式
3. OpenGraph.io 处理请求并返回数据
4. 服务将响应转换为适合 AI 客户端的格式
5. AI 客户端收到可供使用的结构化数据

这种抽象可避免向 AI 直接暴露 API 密钥，同时提供对 OpenGraph.io 功能的完整访问权限。

本地运行

CLI 安装程序和 Claude Desktop 扩展会为你完成设置。若要手动配置客户端，请使用 npx 运行此软件包，并传入你的 OpenGraph.io App ID：

{
  "mcpServers": {
    "opengraph": {
      "command": "npx",
      "args": ["-y", "opengraph-io-mcp"],
      "env": { "OPENGRAPH_APP_ID": "YOUR_OPENGRAPH_APP_ID" }
    }
  }
}

或者，在 shell 中运行 npm install -g opengraph-io-mcp 后：

opengraph-io-mcp --app-id YOUR_APP_ID

本地运行可使用数据和图像生成工具。Open Graph Audit 和 Link Preview 工具需要 OAuth，因此请使用托管服务（参见客户端配置）。

设置	用途
OPENGRAPH_APP_ID（或 APP_ID）	你的 OpenGraph.io App ID。命令行中的 --app-id 作用相同。
MCP_EXPORT_DIR	导出图像的保存文件夹（默认为 ~/Downloads/opengraph-mcp）。

故障排除

• 未显示工具： 更改配置后，重启客户端并检查是否已设置 App ID。使用托管服务时，请在出现提示后完成浏览器登录。
• 缺少 Open Graph Audit 工具： 这些工具仅由支持 OAuth 的托管服务提供。
• Agent 未使用工具： 按名称请求使用该工具，例如“在此页面上使用 getOgMarkdown”。

贡献

npm install
npm run build
npm test

需要 Node 24（参见 .nvmrc）。测试位于 tests/ 中。如何注册工具，请参阅 CLAUDE.md。