scrapegraph-mcp

ScrapeGraph MCP サーバー

Model Context Protocol（MCP）に対応した本番環境向けサーバーです。ScrapeGraph AI APIとシームレスに連携できます。このサーバーにより、言語モデルはエンタープライズレベルの信頼性を備えた高度なAI搭載ウェブスクレイピング機能を活用できます。

目次

• 主な機能
• クイックスタート
• 利用可能なツール
• セットアップ手順
• リモートサーバーの利用
• ローカルでの利用
• Google ADK との連携
• ユースケースの例
• エラー処理
• よくある問題
• 開発
• コントリビューション
• ドキュメント
• 技術スタック
• ライセンス

API v2

この MCP サーバーは ScrapeGraph API v2（https://v2-api.scrapegraphai.com/api）を対象としており、 scrapegraph-py PR #84 と1対1で対応しています。認証には SGAI-APIKEY ヘッダーを使用します。環境変数は Python SDK と同じです。

• SGAI_API_URL — ベース URL を上書きします（デフォルトは https://v2-api.scrapegraphai.com/api）
• SGAI_TIMEOUT — リクエストのタイムアウト時間（秒）（デフォルトは 120）
• SGAI_API_KEY — API キー（MCP の scrapegraphApiKey または X-API-Key ヘッダーでも指定できます）

従来のエイリアス（引き続き使用できます）：SGAI_API_URL の代わりに SCRAPEGRAPH_API_BASE_URL、SGAI_TIMEOUT の代わりに SGAI_TIMEOUT_S を指定します。

主な機能

• スクレイピングと抽出：scrape（POST /scrape、複数形式に対応）、extract（POST /extract、URL とプロンプトを指定）
• 検索：search（POST /search、num_results は3～20に制限）
• クロール：crawl_start / crawl_get_status / crawl_stop / crawl_resume による非同期の複数ページクロール
• スキーマ：schema（POST /schema）— プロンプトから JSON Schema を生成または拡張
• モニター：monitor_create、monitor_list、monitor_get によるスケジュール済みジョブ、停止／再開／削除、monitor_activity（ページ分割された実行履歴）
• アカウント：credits、history
• 簡単に連携：Claude Desktop、Cursor、Smithery、HTTP トランスポート
• 開発者向けドキュメント：.agent/ フォルダー

移行：v2 → v3

v3 では、v2 API ドキュメントと異なっていたすべての MCP ツール名が変更されています。名前を完全に変更し、エイリアスはありません。

v2（旧）	v3（新）
smartscraper	extract
searchscraper	search
smartcrawler_initiate	crawl_start
smartcrawler_fetch_results	crawl_get_status
sgai_history	history
generate_schema	schema
markdownify	削除済み — output_format="markdown" を指定して scrape を使用してください

クイックスタート

1. API キーを取得する

ScrapeGraph Dashboard に登録して、API キーを取得します。

2. Smithery でインストールする（推奨）

npx -y @smithery/cli install @ScrapeGraphAI/scrapegraph-mcp --client claude

3. 利用を開始する

Claude または Cursor に次のように尋ねてください。

• 「https://scrapegraphai.com を Markdown に変換して」
• 「このECサイトのページから商品価格をすべて抽出して」
• 「最新の AI の動向を調べて、調査結果を要約して」

これで完了です。サーバーが AI アシスタントから利用できるようになりました。

利用可能なツール

ツール	役割
scrape	POST /scrape（output_format: markdown、html、screenshot、branding、links、images、summary）
extract	POST /extract（website_url + user_prompt が必要。output_schema は任意）
search	POST /search（num_results は1～20。country_search、time_range、output_schema に対応）
crawl_start	POST /crawl — extraction_mode は markdown / html / links / images / summary / branding / screenshot
crawl_get_status	GET /crawl/:id（status: completed になるまでポーリング）
crawl_stop、crawl_resume	POST /crawl/:id/stop | resume
schema	POST /schema（プロンプトからJSON Schemaを生成または拡張）
credits	GET /credits
history	GET /history（ページネーション、service フィルター）
monitor_create、monitor_list、monitor_get、monitor_pause、monitor_resume、monitor_delete	/monitor API
monitor_activity	GET /monitor/:id/activity（ページネーション対応のティック履歴：id、createdAt、status、changed、elapsedMs、diffs）

削除済み： sitemap、agentic_scrapper、非同期ステータスのポーリング、および（v3で）markdownify — output_format="markdown" を指定して scrape を使用してください。

セットアップ手順

このサーバーを利用するには、ScrapeGraph APIキーが必要です。次の手順で取得してください。

1. ScrapeGraph Dashboard にアクセスします
2. アカウントを作成し、APIキーを生成します

Smitheryによる自動インストール

Smithery を使用してScrapeGraph API Integration Serverを自動インストールするには：

npx -y @smithery/cli install @ScrapeGraphAI/scrapegraph-mcp --client claude

Claude Desktopの設定

次の設定でClaude Desktopの設定ファイルを更新してください（Cursorのページの右上にあります）：

（設定ファイルにAPIキーを追加してください）

{
    "mcpServers": {
        "@ScrapeGraphAI-scrapegraph-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@smithery/cli@latest",
                "run",
                "@ScrapeGraphAI/scrapegraph-mcp",
                "--config",
                "\"{\\\"scrapegraphApiKey\\\":\\\"YOUR-SGAI-API-KEY\\\"}\""
            ]
        }
    }
}

設定ファイルの場所：

• Windows：%APPDATA%/Claude/claude_desktop_config.json
• macOS：~/Library/Application\ Support/Claude/claude_desktop_config.json

Cursorとの連携

設定でScrapeGraphAI MCPサーバーを追加します：

リモートサーバーの使用方法

ホストされているMCPサーバーに接続できます。ローカルへのインストールは不要です！

警告

従来のMCPエンドポイント https://mcp.scrapegraphai.com/mcp は、まもなく 非推奨となる予定です。新しい連携では、代替のMCPエンドポイント https://sgai-mcp-main.onrender.com を使用してください。

Claude Desktopの設定（リモート）

次の内容をClaude Desktopの設定ファイルに追加してください（macOSでは ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "scrapegraph-mcp": {
      "command": "npx",
      "args": [
        "[email protected]",
        "https://sgai-mcp-main.onrender.com",
        "--header",
        "X-API-Key:YOUR_API_KEY"
      ]
    }
  }
}

Cursorの設定（リモート）

CursorはネイティブのHTTP MCP接続に対応しています。CursorのMCP設定（~/.cursor/mcp.json）に追加してください：

{
  "mcpServers": {
    "scrapegraph-mcp": {
      "url": "https://sgai-mcp-main.onrender.com",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

リモートサーバーのメリット

• ローカルでのセットアップ不要 — 設定するだけですぐに使用できます
• 常に最新 — 最新の更新が自動的に適用されます
• クロスプラットフォーム — Node.jsを搭載したあらゆるOSで動作します

ローカルでの使用方法

開発またはテストのためにMCPサーバーをローカルで実行するには、次の手順に従ってください：

前提条件

• Python 3.13以降
• pipまたはuvパッケージマネージャー
• ScrapeGraph APIキー

インストール

1. リポジトリをクローンします（まだクローンしていない場合）：

git clone https://github.com/ScrapeGraphAI/scrapegraph-mcp
cd scrapegraph-mcp

2. パッケージをインストールします：

# Using pip
pip install -e .

# Or using uv (faster)
uv pip install -e .

3. APIキーを設定します：

# macOS/Linux
export SGAI_API_KEY=your-api-key-here

# Windows (PowerShell)
$env:SGAI_API_KEY="your-api-key-here"

# Windows (CMD)
set SGAI_API_KEY=your-api-key-here

サーバーをローカルで実行する

サーバーを直接実行できます：

# Using the installed command
scrapegraph-mcp

# Or using Python module
python -m scrapegraph_mcp.server

サーバーが起動し、標準的なMCPトランスポート方式であるstdio（標準入出力）を介して通信します。

MCP Inspectorでテストする

MCP Inspectorツールを使用して、ローカルサーバーをテストします：

npx @modelcontextprotocol/inspector python -m scrapegraph_mcp.server

すべての利用可能なツールをインタラクティブにテストできるWebインターフェースが表示されます。

ローカルサーバー用の Claude Desktop の設定

ローカルで実行中のサーバーを Claude Desktop で使用するには、設定ファイルを更新します。

macOS/Linux（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
    "mcpServers": {
        "scrapegraph-mcp-local": {
            "command": "python",
            "args": [
                "-m",
                "scrapegraph_mcp.server"
            ],
            "env": {
                "SGAI_API_KEY": "your-api-key-here"
            }
        }
    }
}

Windows（%APPDATA%\Claude\claude_desktop_config.json）：

{
    "mcpServers": {
        "scrapegraph-mcp-local": {
            "command": "python",
            "args": [
                "-m",
                "scrapegraph_mcp.server"
            ],
            "env": {
                "SGAI_API_KEY": "your-api-key-here"
            }
        }
    }
}

注：Python が PATH に含まれていることを確認してください。ターミナルで python --version を実行すると確認できます。

ローカルサーバー用の Cursor の設定

Cursor の MCP 設定で、新しいサーバーを次のように追加します。

• コマンド：python
• 引数：["-m", "scrapegraph_mcp.server"]
• 環境変数：{"SGAI_API_KEY": "your-api-key-here"}

ローカル環境のトラブルシューティング

サーバーが起動しない場合：

• Python がインストールされていることを確認します：python --version
• パッケージがインストールされていることを確認します：pip list | grep scrapegraph-mcp
• API キーが設定されていることを確認します：echo $SGAI_API_KEY（macOS/Linux）または echo %SGAI_API_KEY%（Windows）

ツールが表示されない場合：

• Claude Desktop のログを確認します：
  • macOS：~/Library/Logs/Claude/
  • Windows：%APPDATA%\Claude\Logs\
• サーバーを直接実行したときにエラーなく起動することを確認します
• 設定 JSON が有効であることを確認します

インポートエラーが発生する場合：

• パッケージを再インストールします：pip install -e . --force-reinstall
• 依存関係を確認します：pip install -r requirements.txt（利用可能な場合）

Google ADK との統合

ScrapeGraph MCP サーバーは、Google ADK（Agent Development Kit）と統合して、ウェブスクレイピング機能を備えた AI エージェントを作成できます。

前提条件

• Python 3.13 以降
• Google ADK がインストールされていること
• ScrapeGraph API キー

インストール

1. Google ADK をインストールします（まだインストールされていない場合）。

pip install google-adk

2. API キーを設定します。

export SGAI_API_KEY=your-api-key-here

基本的な統合例

次の設定でエージェントファイル（例：agent.py）を作成します。

import os
from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

# Path to the scrapegraph-mcp server directory
SCRAPEGRAPH_MCP_PATH = "/path/to/scrapegraph-mcp"

# Path to the server.py file
SERVER_SCRIPT_PATH = os.path.join(
    SCRAPEGRAPH_MCP_PATH, 
    "src", 
    "scrapegraph_mcp", 
    "server.py"
)

root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='scrapegraph_assistant_agent',
    instruction='Help the user with web scraping and data extraction using ScrapeGraph AI. '
                'You can convert webpages to markdown, extract structured data using AI, '
                'perform web searches, crawl multiple pages, and automate complex scraping workflows.',
    tools=[
        MCPToolset(
            connection_params=StdioConnectionParams(
                server_params=StdioServerParameters(
                    command='python3',
                    args=[
                        SERVER_SCRIPT_PATH,
                    ],
                    env={
                        'SGAI_API_KEY': os.getenv('SGAI_API_KEY'),
                    },
                ),
                timeout=300.0,)
            ),
            # Optional: Filter which tools from the MCP server are exposed
            # tool_filter=['scrape', 'extract', 'search']
        )
    ],
)

設定オプション

タイムアウト設定：

• デフォルトのタイムアウトは 5 秒です。ウェブスクレイピングの処理には短すぎる場合があります
• 推奨：timeout=300.0 を設定します
• 用途に応じて調整してください（クロール処理では、さらに長いタイムアウトが必要になる場合があります）

ツールのフィルタリング：

• デフォルトでは、登録済みのすべての MCP ツールがエージェントに公開されます（利用可能なツールを参照）
• tool_filter を使用して、利用可能なツールを制限します：

  tool_filter=['scrape', 'extract', 'search']
  

API キーの設定：

• 環境変数で設定します：export SGAI_API_KEY=your-key
• または、env 辞書に直接渡します：'SGAI_API_KEY': 'your-key-here'
• セキュリティ上、環境変数を使用する方法を推奨します

使用例

設定が完了すると、エージェントは自然言語を使ってウェブスクレイピングツールを操作できます。

# The agent can now handle queries like:
# - "Convert https://example.com to markdown"
# - "Extract all product prices from this e-commerce page"
# - "Search for recent AI research papers and summarize them"
# - "Crawl this documentation site and extract all API endpoints"

Google ADK の詳細については、公式ドキュメントを参照してください。

使用例

このサーバーを使うと、さまざまなスクレイピングのシナリオで高度なクエリを実行できます。

単一ページのスクレイピング

• Markdownify：「ScrapeGraph のドキュメントページを Markdown に変換してください」
• Extract：「この EC サイトのページから、商品名、価格、評価をすべて抽出してください」
• スクロール付きの抽出：「この無限スクロールページを 5 回スクロールしてスクレイピングし、すべての項目を抽出してください」
• 基本的なスクレイピング：「この JavaScript を多用するページを完全にレンダリングして、HTML コンテンツを取得してください」

検索と調査

• 検索：「AI を活用したウェブスクレイピングの最近の動向を調査し、要約してください」
• 検索：「機械学習フレームワークに関する記事の上位 5 件を検索し、重要な知見を抽出してください」
• 検索：「GPT-4 に関する最近のニュースを見つけ、構造化された要約を作成してください」
• 検索：v2 では time_range は適用されません。代わりに、自然言語でクエリを表現し、最近の情報を優先するようにしてください

ウェブサイトの分析

• crawl_start と crawl_get_status を組み合わせて、複数ページのコンテンツをマッピングして取得します。v2 には独立した sitemap ツールはありません。

複数ページのクロール

• クロール：「ブログを Markdown モードでクロールし、完了するまで状態を確認してください」
• ページごとの構造化フィールドを取得するには、個々の URL に対して extract を実行します（または、スケジュールに従って monitor_create を実行します）

モニターとアカウント

• モニター：「毎日午前9時に https://example.com でこの抽出プロンプトを実行する」（間隔を指定して monitor_create）
• クレジット／履歴：credits、history
• エージェント型スクレーパー：「ログインし、レポートに移動して、データをダウンロードし、要約統計を抽出する複雑なワークフローを実行する」

エラー処理

サーバーは、次の項目について、詳細で対処可能なエラーメッセージを含む堅牢なエラー処理を実装しています。

• API 認証の問題
• 不正な URL 構造
• ネットワーク接続の失敗
• レート制限とクォータ管理

よくある問題

Windows 固有の接続

Windows システムで実行する場合、MCP サーバーに接続するために次のコマンドが必要になることがあります。

C:\Windows\System32\cmd.exe /c npx -y @smithery/cli@latest run @ScrapeGraphAI/scrapegraph-mcp --config "{\"scrapegraphApiKey\":\"YOUR-SGAI-API-KEY\"}"

これにより、Windows 環境で適切に実行できます。

その他のよくある問題

「ScrapeGraph client not initialized」

• 原因：API キーが設定されていません
• 解決策：SGAI_API_KEY 環境変数を設定するか、--config で指定してください

「Error 401: Unauthorized」

• 原因：API キーが無効です
• 解決策：ScrapeGraph Dashboard で API キーを確認してください

「Error 402: Payment Required」

• 原因：クレジットが不足しています
• 解決策：ScrapeGraph アカウントにクレジットを追加してください

クロールで結果が返されない

• 原因：処理中です（非同期操作）
• 解決策：ステータスが「completed」になるまで crawl_get_status() を繰り返し呼び出してください

Claude Desktop にツールが表示されない

• 原因：サーバーが起動していないか、設定にエラーがあります
• 解決策：Claude のログを ~/Library/Logs/Claude/（macOS）または %APPDATA%\Claude\Logs\（Windows）で確認してください

詳細なトラブルシューティングについては、.agent documentation を参照してください。

開発

前提条件

• Python 3.13 以降
• pip または uv パッケージマネージャー
• ScrapeGraph API キー

ソースからのインストール

# Clone the repository
git clone https://github.com/ScrapeGraphAI/scrapegraph-mcp
cd scrapegraph-mcp

# Install dependencies
pip install -e ".[dev]"

# Set your API key
export SGAI_API_KEY=your-api-key

# Run the server
scrapegraph-mcp
# or
python -m scrapegraph_mcp.server

MCP Inspector を使用したテスト

MCP Inspector ツールを使用して、サーバーをローカルでテストします。

npx @modelcontextprotocol/inspector scrapegraph-mcp

これにより、利用可能なすべてのツールをテストするためのウェブインターフェースが提供されます。

コード品質

Lint チェック：

ruff check src/

型チェック：

mypy src/

フォーマットチェック：

ruff format --check src/

プロジェクト構成

scrapegraph-mcp/
├── src/
│   └── scrapegraph_mcp/
│       ├── __init__.py      # Package initialization
│       └── server.py        # Main MCP server (all code in one file)
├── .agent/                  # Developer documentation
│   ├── README.md           # Documentation index
│   └── system/             # System architecture docs
├── assets/                  # Images and badges
├── pyproject.toml          # Project metadata & dependencies
├── smithery.yaml           # Smithery deployment config
└── README.md               # This file

コントリビューション

コントリビューションを歓迎します。次の方法でご協力いただけます。

新しいツールの追加

1. server.py の ScapeGraphClient クラスにメソッドを追加します。

def new_tool(self, param: str) -> Dict[str, Any]:
    """Tool description."""
    url = f"{self.BASE_URL}/new-endpoint"
    data = {"param": param}
    response = self.client.post(url, headers=self.headers, json=data)
    if response.status_code != 200:
        raise Exception(f"Error {response.status_code}: {response.text}")
    return response.json()

2. MCP ツールデコレーターを追加します：

@mcp.tool()
def new_tool(param: str) -> Dict[str, Any]:
    """
    Tool description for AI assistants.

    Args:
        param: Parameter description

    Returns:
        Dictionary containing results
    """
    if scrapegraph_client is None:
        return {"error": "ScrapeGraph client not initialized. Please provide an API key."}

    try:
        return scrapegraph_client.new_tool(param)
    except Exception as e:
        return {"error": str(e)}

3. MCP Inspector でテストします：

npx @modelcontextprotocol/inspector scrapegraph-mcp

4. ドキュメントを更新します：

   • この README にツールを追加します
   • .agent documentation を更新します

5. プルリクエストを送信します

開発ワークフロー

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更を加えます
4. lint チェックと型チェックを実行します
5. MCP Inspector と Claude Desktop でテストします
6. ドキュメントを更新します
7. 変更をコミットします（git commit -m 'Add amazing feature'）
8. ブランチにプッシュします（git push origin feature/amazing-feature）
9. プルリクエストを作成します

コードスタイル

• 行の長さ：100 文字
• 型ヒント：すべての関数で必須
• Docstring：Google スタイルの docstring
• エラー処理：エラーディクショナリを返し、ツール内で例外を発生させないでください
• Python バージョン：3.13 以降を対象とします

詳細な開発ガイドラインについては、.agent documentation を参照してください。

ドキュメント

開発者向けの包括的なドキュメントについては、以下を参照してください。

• .agent/README.md - 開発者向けドキュメントの完全なインデックス
• .agent/system/project_architecture.md - システムアーキテクチャと設計
• .agent/system/mcp_protocol.md - MCP プロトコル統合の詳細

技術スタック

コアフレームワーク

• Python 3.13+ - 型ヒントに対応した最新の Python
• FastMCP - 軽量な MCP サーバーフレームワーク
• httpx 0.24.0+ - 最新の非同期 HTTP クライアント

開発ツール

• Ruff - 高速な Python リンターおよびフォーマッター
• mypy - 静的型チェッカー
• Hatchling - モダンなビルドバックエンド

デプロイ

• Smithery - MCP サーバーの自動デプロイ
• Docker - Alpine Linux によるコンテナーサポート
• stdio transport - 標準の MCP 通信

API 連携

• ScrapeGraph AI API - エンタープライズ向けウェブスクレイピングサービス
• Base URL: https://v2-api.scrapegraphai.com/api
• 認証: API キーベース

ライセンス

このプロジェクトは MIT ライセンスの下で配布されています。詳細な利用規約については、LICENSE ファイルを参照してください。

謝辞

このリポジトリの出発点となった oura-mcp-server の実装を提供してくださった tomekkorbak に、心より感謝申し上げます。

リソース

公式リンク

• ScrapeGraph AI ホームページ
• ScrapeGraph ダッシュボード - API キーを取得
• ScrapeGraph API ドキュメント
• GitHub リポジトリ

MCP リソース

• Model Context Protocol - MCP の公式仕様
• FastMCP フレームワーク - このサーバーで使用しているフレームワーク
• MCP Inspector - テストツール
• Smithery - MCP サーバーの配布
• mcp-name: io.github.ScrapeGraphAI/scrapegraph-mcp

AI アシスタントとの連携

• Claude Desktop - MCP に対応したデスクトップアプリ
• Cursor - AI 搭載のコードエディター

サポート

• GitHub Issues - バグの報告や機能のリクエスト
• 開発者向けドキュメント - 開発に関する包括的なドキュメント

---

❤️ を込めて ScrapeGraphAI チームが作成