Opengraph.io

OpenGraph MCP サーバー

opengraph-io-mcp は、標準の MCP インターフェースを通じて、Claude、Cursor、LangGraph などの AI エージェントが OpenGraph.io API を利用できるようにする Model Context Protocol（MCP）サーバーです。

なぜでしょうか？ リンクの展開、HTML のスクレイピング、記事本文の抽出、スクリーンショットの取得にすでに OpenGraph.io を使っているなら、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 では、リリースページから .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

Settings → Connectors → Add custom connector を選択し、名前に 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（context_servers を使用する ~/.config/zed/settings.json）：

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

利用可能なツール

2 つの認証階層： データツールと画像生成ツールは 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 エンドポイント	説明	ドキュメント
OG データを取得	/api/3.0/site/<URL>	Open Graph メタデータ、HTML から推定したタグ、ハイブリッド形式のソーシャルプレビュー情報を取得します。use_ai、ai_sanitize、追加読み込み、プロキシ／再試行、および v3 のすべてのスマートデフォルトに対応しています。	ドキュメント
OG スクレイピングデータを取得	/api/3.0/scrape/<URL>	ページ最下部へのスクロール、追加読み込みボタンのクリック、AI によるサニタイズなど、v3 のすべてのレンダリングオプションを使用して、生の HTML をスクレイピングします。	ドキュメント
OG スクリーンショットを取得	/api/3.0/screenshot/<URL>	スクリーンショットを撮影します。full_page、dark_mode、capture_delay、navigationTimeout、hideSelectors、カスタムビューポートサイズに対応しています。	ドキュメント
OG クエリを取得	/api/1.1/query/<URL>	ページのコンテンツについて自然言語で質問します。v3 用に課金経路が更新されるまでは、v1.1 を使用します（リクエストごとに 100～200 クレジット）。	ドキュメント
OG 抽出を取得	/api/1.1/extract/<URL>	タグ名で指定して、特定の HTML 要素（h1、p、a、img など）を抽出します。このエンドポイントには v3 の GET ルートがないため、v1.1 を使用します。	ドキュメント
OG Markdown を取得	/api/3.0/markdown/<URL>	任意の URL の HTML を、読みやすい Markdown に変換します。デフォルトでナビゲーションと広告を除去し（only_main_content: true）、include_tags／exclude_tags セレクターに対応しています。長いページでは、chunking とともに query を渡すと、ドキュメント全体ではなく、関連度順に並べた関連箇所だけを取得できます。include_links／include_images／include_headings を指定すると、リンク、画像、アウトラインの構造化データが返されます。ページのメタデータ、文字数とトークンの使用量が返されます。また、ai_sanitize を指定すると、プロンプトインジェクションに関する安全性レポートも返されます。	ドキュメント

言語検出： すべてのツールはデフォルトで accept_lang: auto を送信し、リクエストの Accept-Language ヘッダーを反映します。上書きするには、明示的な BCP 47 タグ（例：en-US、fr）を渡してください。

Open Graph 監査とリンクプレビューツール

OAuth 2.1 が必要です（認証を参照）。また、Open Graph Audit を含むプランが必要です。これらのツールはホスト型サーバーでのみ利用できます。サーバーをローカルで実行する場合（CLI インストーラーまたは Claude Desktop 拡張機能）、あるいは x-app-id ヘッダーを使用して接続する場合には、一覧に表示されません。API キーだけでなく、組織の ID が必要なためです。

ツール名	説明
サイト 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 Audit のスケジュール設定権限が必要です。

ツール名	説明
ウェブサイトを一覧表示	組織が監査したすべてのサイトについて、現在のスコアと前回の実行結果との傾向、重大な問題とリグレッションの件数、把握済みのページ数、次回の予定実行日時を表示します。websiteId を渡すと、1 件の詳細を表示します。
Open Graph 監査を一覧表示	過去の監査を新しい順に表示します。ドメイン、ステータス、日付範囲、またはウェブサイトで絞り込めます。
Open Graph 監査の変更を取得	前回の実行以降の変更を表示します。新規、修正済み、リグレッションした問題、追加または削除されたページ、スコアの差分に加え、優先順位付きの問題グループも含まれます。リグレッションした問題とは、以前に修正済みと確認されたものの、再発した問題です。これは 2 つのリストの差分比較ではなく、永続的な問題 ID に基づいて実行ごとに追跡されます。
監視スケジュールを取得	ウェブサイトの定期監査設定を表示します。頻度、基準となる曜日と時刻、一時停止状態、次回の実行日時が含まれます。
監視スケジュールを設定	定期監査を有効化、変更、または削除します。継続的なページクォータの消費を確定し、アラートメールが送信される場合があります。enabled: false は設定を削除します。設定を残すには paused: true を使用してください。アラートの受信者はダッシュボードでのみ設定できます。
接続コンテキストを取得	この接続がどの組織として動作するか、また、その組織のプランでどの Open Graph Audit 機能が利用できるかを表示します。組織は認証時に選択され、すべてのツールで既定の対象となります。

修正リストツール

監査結果を、開発者が実行できる作業に変換します。OAuth が必要です。

ツール名	説明
修正項目を一覧表示	監査に保存されたメタデータの変更案とメモを、ページごとにグループ化して ID とともに表示します。
修正項目を保存	1 つのページの変更案を記録します。同じページとフィールドにある既存項目は上書きされます。空の proposedValue または変更されていない proposedValue は拒否されます。これは上流では「削除」を意味するため、意図的に 修正項目を削除 を使用してください。
修正項目を削除	1 つの項目を完全に削除します。修正項目は手動で作成されるもので、再監査しても再生成されません。
修正項目を CSV でエクスポート	引き継ぎ用の修正リストを CSV テキストとして出力します。PDF エクスポートはダッシュボードでのみ利用できます。
Open Graph 監査レポートをメール送信	PDF 添付ファイル付きのレポートを、認証済みアカウント自身のメールアドレスに送信します。呼び出すたびに実際のメールが送信され、冪等ではありません。受信者は指定できません。

画像生成ツール

ツール名	説明
画像を生成	イラスト、図（Mermaid／D2／Vega）、アイコン、ソーシャルカード、QR コードなどのプロ品質の画像を作成します。
画像を反復	既存の生成画像を調整、変更したり、バリエーションを作成したりします。
画像セッションを検査	画像生成セッションのメタデータとアセット履歴を取得します。
画像アセットをエクスポート	生成した画像アセットをインライン base64 としてエクスポートします。ローカル実行時は、オプションでディスクに書き込めます。

画像生成

サーバーには強力な AI 駆動の画像生成機能が備わっており、ソーシャルメディアカード、アーキテクチャ図、アイコンなどの作成に最適です。

画像を生成

自然言語のプロンプトまたは図のコードから画像を作成します。

対応する画像の種類（kind）：

• illustration - 汎用の AI 生成画像
• diagram - Mermaid、D2、または Vega 構文から作成する技術図
• icon - アプリのアイコンやロゴ
• social-card - ソーシャル共有に最適化された OG 画像
• qr-code - オプションでスタイルを設定できる QR コード

プリセットのアスペクト比：

• ソーシャル：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"
})

画像を反復

既存の生成画像を調整または変更します。

用途：

• 特定の部分を編集：「背景を青に変更」
• スタイルを変更：「もっとミニマルに」
• 問題を修正：「テキストを削除」「アイコンを大きく」
• 指定した座標にトリミング

例：

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

画像セッションを検査

セッションの詳細を確認し、反復に使うアセット ID を調べます。

返される内容：

• セッションのメタデータ（作成時刻、名前、ステータス）
• プロンプト、ツールチェーン、ステータスを含むすべてのアセットの一覧
• 反復履歴を示す親子関係

例：

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

画像アセットのエクスポート

セッションとアセット ID を指定して、生成された画像アセットをエクスポートします。メタデータ（形式、寸法、サイズ）とともに、画像を base64 形式でインラインに返します。

ローカルで実行する場合（stdio トランスポート）、オプションで destinationPath を指定して、画像をディスクに保存できます。ホスト型の HTTP トランスポートでは、このパスは無視され、画像はインラインでのみ返されます。

ファイルは、1 つのエクスポートフォルダー内にのみ書き込まれます。デフォルトでは ~/Downloads/opengraph-mcp、または MCP_EXPORT_DIR で指定したフォルダーです。このフォルダー内のファイル名またはパスを渡してください。フォルダー外のパスは拒否され、隠しファイルや隠しフォルダーも拒否されます。拡張子は画像の種類と一致している必要があります（拡張子がない名前には自動で追加されます）。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 クライアントがユーザーに直接提示できる（スラッシュコマンドなど）、またはエージェントが自由形式のツール呼び出しより確実な結果を得るために名前で呼び出せる、事前に構築された複数ステップのワークフローです。

プロンプト名	機能
analyze-webpage	ページのメタデータと読みやすいコンテンツを並行して取得し、要約するか、ページに関する特定の質問に回答します。
extract-structured-data	CSS セレクターを使って、ページから指定されたフィールド（タイトル、価格、SKU など）を抽出します。EC サイト、求人情報、記事に最適です。
get-page-content	URL を、定型的な部分を取り除いた読みやすいテキスト／Markdown に変換します。すぐに読んだり、別のモデルに渡したりできます。
run-site-audit	サイト全体の監査ワークフローです。希望する範囲（サイト全体／主要ページ／特定のセクション／コードベースのスキャン）をユーザーに尋ね、必要に応じて URL を検出し、監査を開始して、ステータスを確認し、読みやすいレポートを返します。OAuth が必要です。
create-branded-diagram	ブランドアイデンティティに合った図（フローチャート、シーケンス図、アーキテクチャ図、ER 図、状態遷移図）の作成をガイドするワークフローです。
iterate-and-refine	以前に生成した画像を繰り返し改良し、望ましい結果に近づけるためのベストプラクティスです。
create-asset-set	視覚的に一貫性のあるアイコン、ソーシャルカード、図、イラストのセットを生成します。
quick-icon	適切なデフォルト設定で、単一のアイコンをすばやく生成します。

仕組み

^{このサーバーの画像生成ツールを使って作成した図}

このサーバーは、AI クライアント（Claude やその他の LLM など）と OpenGraph.io API の間のブリッジとして機能します。

1. AI クライアントが、利用可能な MCP 関数の 1 つをツールとして呼び出します
2. サーバーがリクエストを受信し、OpenGraph.io API 向けに形式を整えます
3. OpenGraph.io がリクエストを処理し、データを返します
4. サーバーがレスポンスを AI クライアントに適した形式に変換します
5. AI クライアントが、すぐに利用できる構造化データを受け取ります

この抽象化により、API キーを AI に直接公開することなく、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" }
    }
  }
}

または、シェルで 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 を使用するホステッドサーバーでのみ提供されています。
• エージェントがツールを使用しない： 「このページで getOgMarkdown を使って」のように、ツール名を指定して依頼してください。

貢献

npm install
npm run build
npm test

Node 24 が必要です（.nvmrc を参照）。テストは tests/ にあります。ツールの登録方法については CLAUDE.md を参照してください。