DataForSEO MCP Server

DataForSEO MCP サーバー

これは新しい v3 MCP サーバーです。 以前の v2+ MCP サーバーは非推奨で、dataforseo/mcp-server-typescript-deprecated にあります。

LLM エージェントが DataForSEO API のドキュメントを参照し、認証済み API リクエストを行うための MCP サーバーおよび CLI です。デフォルトではバイナリは stdio で MCP サーバーを起動します。CLI コマンドは追加のモードとして任意で使用できます。

クイックスタート

stdio で MCP サーバーを起動します（デフォルトモード。DATAFORSEO_LOGIN／DATAFORSEO_PASSWORD を設定してください）。

npx dataforseo-mcp-server@latest

HTTP トランスポート（ポート 3000。PORT で変更できます）。

npx dataforseo-mcp-server@latest --mode http

認証

OAuth 2.0（HTTP MCP のデフォルト）： 追加設定なしで動作します。MCP クライアントは Protected Resource メタデータを通じて DataForSEO 認可サーバーを検出し、Authorization: Bearer トークンを送信します。

フォールバック： 環境変数で指定する API ログイン／パスワード（HTTP Basic）です。CLI と stdio MCP では必須です。HTTP では Authorization ヘッダーがない場合に使用されます。

# bash / macOS / Linux
export DATAFORSEO_LOGIN="your_api_login"
export DATAFORSEO_PASSWORD="your_api_password"

# PowerShell
$env:DATAFORSEO_LOGIN="your_api_login"
$env:DATAFORSEO_PASSWORD="your_api_password"

REM CMD
set DATAFORSEO_LOGIN=your_api_login
set DATAFORSEO_PASSWORD=your_api_password

DATAFORSEO_USERNAME は DATAFORSEO_LOGIN の別名として使用できます。https://app.dataforseo.com/api-access で API キーを取得してください。

MCP サーバー

同じツール実装が MCP サーバーと CLI の両方で使用されます。1 つのバイナリで両方のモードに対応しており、デフォルトは MCP です。

バイナリのモード選択方法：

• MCP stdio — CLI コマンドが指定されていない場合のデフォルト
• MCP HTTP — --mode http を指定します（ポート 3000 で Streamable HTTP を使用。PORT で変更できます）
• CLI — 最初のコマンドが docs または request の場合、あるいは --cli／--help／--version が指定された場合

MCP stdio（デフォルト）：

npx dataforseo-mcp-server

MCP HTTP：

npx dataforseo-mcp-server --mode http

CLI：

npx dataforseo-mcp-server docs index

MCP クライアントの設定（Cursor、Claude Desktop、および mcpServers を使用する同様のクライアント）：

URL 経由 — ホストされたリモート MCP サーバーを使用するか、ローカル HTTP サーバー（npx dataforseo-mcp-server --mode http）を起動し、クライアントから接続します。OAuth は追加設定なしで動作します。環境変数による認証情報は、任意のフォールバックとしてのみ使用されます。

公開リモート MCP サーバー URL：https://mcp.dataforseo.com/v3/mcp

{
  "mcpServers": {
    "dataforseo": {
      "url": "https://mcp.dataforseo.com/v3/mcp"
    }
  }
}

ローカルサーバー（デフォルトのポート 3000）：

{
  "mcpServers": {
    "dataforseo": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

command 経由（stdio）— クライアントがバイナリ自体を起動します（stdio はデフォルトモードです）。このトランスポートでは OAuth は使用されません。環境変数を設定するか、MCP クライアントの env ブロックに認証情報を渡してください。

{
  "mcpServers": {
    "dataforseo": {
      "command": "npx",
      "args": [
        "dataforseo-mcp-server",
        // Optional additional args:
        // "--docs-cache-dir", "D:\\my-docs-cache",
        // "--configuration", "field-config.json"
      ],
      "env": {
        "DATAFORSEO_LOGIN": "your_api_login",
        "DATAFORSEO_PASSWORD": "your_api_password",
        // Optional additional env:
        // "FIELD_CONFIG_PATH": "field-config.json"
      }
    }
  }
}

開発時にリポジトリのルートから実行する場合：

{
  "mcpServers": {
    "dataforseo": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/path/to/mcp-server-typescript"
    }
  }
}

MCP ツール

ツール	タイトル	説明
docs_index	ドキュメントインデックス	ドキュメントのインデックスを取得します。必要に応じてセクションで絞り込めます（24 時間キャッシュ）
docs_list_sections	ドキュメントセクション一覧	利用可能なドキュメントのセクション名を返します
docs_search	ドキュメント検索	ドキュメント URL からドキュメントを取得します（needCodeExample、24 時間キャッシュ）
api_request	API リクエスト	認証済み API リクエストを行います

api_request はデフォルトで .ai パスを使用します。MCP リクエストで noAiMode を true に設定するか、CLI で --no-ai-mode を指定すると、標準パスを使用できます。リクエスト本文は data（JSON オブジェクトまたは配列）として渡します。--param オプションは CLI 専用です。

HTTP トランスポート

Streamable HTTP エンドポイント：

• POST /mcp
• POST /http

OAuth 2.0 Protected Resource メタデータ（RFC 9728）は常に公開されるため、MCP クライアントは認可サーバーを検出し、Bearer トークンで認証できます。

• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-protected-resource/mcp
• GET /.well-known/oauth-protected-resource/http

リバースプロキシの背後で使用する場合は、メタデータ URL が https を使用するように TRUST_PROXY=true を設定してください。

HTTP リクエストでの認証の優先順位：

1. Authorization: Basic ヘッダー
2. Authorization: Bearer ヘッダー（OAuth アクセストークン）
3. 環境変数の認証情報（DATAFORSEO_LOGIN／DATAFORSEO_PASSWORD）— Authorization ヘッダーが送信されない場合のフォールバック

CLI（任意）

MCP に加えて、同じバイナリから CLI コマンドとして docs と request を実行できます。

コマンド

コマンド	説明
npx dataforseo-mcp-server docs index	API ドキュメントのインデックス全体を取得します
npx dataforseo-mcp-server docs index --section "SERP API"	API セクションでインデックスを絞り込みます
npx dataforseo-mcp-server docs index --list-sections	利用可能なセクションを一覧表示します
npx dataforseo-mcp-server docs search <url>	ドキュメントの URL またはパスからドキュメントを取得します（デフォルトでは cURL の例のみ）
npx dataforseo-mcp-server docs search <url> --need-code-example	PHP、Node.js、Python、C# の例を含むドキュメントを取得します
npx dataforseo-mcp-server request -X <method> -p <path>	認証済み API リクエストを送信します（デフォルトでは .ai パス）

ビルド済みのローカルクローンからは、npx dataforseo-mcp-server の代わりに npx . も使用できます。

例

# Browse SERP API endpoints
npx dataforseo-mcp-server docs index --section "SERP API"

# Read endpoint documentation (path or full docs URL)
npx dataforseo-mcp-server docs search serp/google/organic/live/regular
npx dataforseo-mcp-server docs search https://docs.dataforseo.com/v3/serp/google/organic/live/regular

# Include multi-language code examples (PHP, Node.js, Python, C#)
npx dataforseo-mcp-server docs search backlinks/referring_networks/live --need-code-example

# Live SERP request (recommended: use --param)
npx dataforseo-mcp-server request -X POST -p /v3/serp/google/organic/live/regular \
  --param keyword=dataforseo --param language_code=en --param location_code=2840

# Same request via JSON body
npx dataforseo-mcp-server request -X POST -p /v3/serp/google/organic/live/regular \
  -d '[{"keyword":"dataforseo","location_code":2840,"language_code":"en"}]'

ドキュメントのレスポンスは 24 時間キャッシュされます。デフォルトのキャッシュディレクトリ：

• Windows: %LOCALAPPDATA%\dataforseo-mcp-server\docs-cache
• macOS: ~/Library/Caches/dataforseo-mcp-server/docs-cache
• Linux: ~/.cache/dataforseo-mcp-server/docs-cache（または $XDG_CACHE_HOME）

CLI の docs コマンドで --cache-dir <path> を指定すると、キャッシュディレクトリを変更できます。MCP の場合は、サーバー起動時の args に --docs-cache-dir <path> を渡します。

API レスポンスはレスポンスボディのみで返されます（可能な場合は JSON として解析されます）。フィールド設定が読み込まれている場合、api_request / request のレスポンスは、そのエンドポイントパスに設定されたフィールドに絞り込まれます（フィールド設定を参照）。

フィールド設定

API レスポンスで返されるフィールドを任意で制限できます。以前の複数ツール対応 MCP サーバー（キー＝ツール名）とは異なり、このパッケージでは API エンドポイントのパスをキーとして設定します。

# MCP stdio (default when no CLI command is passed)
npx dataforseo-mcp-server --configuration field-config.json

# MCP HTTP
npx dataforseo-mcp-server --mode http --configuration field-config.json

# CLI
npx dataforseo-mcp-server --configuration field-config.json request -X POST -p /v3/backlinks/summary/live --param target=example.com

または、環境変数を設定します：

• FIELD_CONFIG_PATH — JSON ファイルへのパス（Node）
• FIELD_CONFIG_JSON — インライン JSON 文字列（Node / Cloudflare Worker）

最小限の例（より詳細な例は field-config.example.json を参照）：

{
  "supported_fields": {
    "/v3/serp/google/organic/live/advanced": ["id", "items.title", "items.url", "status_code"],
    "/v3/backlinks/summary/live": ["id", "items.backlinks", "items.referring_domains", "status_code"]
  }
}

動作：

• /v3/on_page/lighthouse/live/json には組み込みのデフォルト設定が常に適用されます（Lighthouse のペイロードを縮小）。カスタム設定はその上にマージされ、任意のパスを上書きできます。
• パスの照合では、.ai サフィックス、末尾のスラッシュ、ホストは無視されます（完全な URL も使用できます）。
• パスに空でないフィールドリストが設定されている場合 → 指定されたフィールドのみが保持されます（各 tasks[].result[] 項目に適用）。
• パスに空のフィールドリスト [] が設定されている場合 → そのパスのレスポンス全体が返されます（フィルタリングを無効化）。
• デフォルト設定とカスタム設定のどちらにもパスがない場合 → レスポンス全体が返されます。

例をコピーし、使用するエンドポイントに合わせて絞り込んでください：

cp field-config.example.json my-config.json

アーキテクチャ

src/
├── index.ts            # Unified entry (MCP by default stdio; CLI if docs/request/--cli)
├── config/             # URLs, sections, auth server
├── core/
│   ├── api/            # auth, client, path, request-body
│   ├── cli/            # program, error, output
│   ├── config/         # field configuration + defaults
│   ├── docs/           # path, section, cache
│   ├── http/           # fetch
│   ├── mcp/            # startup args (--configuration, --docs-cache-dir)
│   ├── tools/          # shared CLI + MCP tool implementations
│   ├── utils/          # field filter
│   ├── env.ts
│   └── version.ts
├── mcp/
│   ├── init-mcp-server.ts
│   ├── tool-definition.ts
│   ├── auth-middleware.ts
│   ├── http-routes.ts
│   ├── index.ts        # stdio transport
│   └── index-http.ts   # streamable HTTP
└── worker/             # Cloudflare Worker entry (built separately)

ビルド出力

ターゲット	コマンド	出力	使用先
Node（MCP + CLI）	npm run build（tsc）	dist/index.js	bin、Docker、start* スクリプト
Cloudflare Worker	npm run worker:build	build/worker/worker/index-worker.js	wrangler.jsonc → main

Worker のパスが build/worker/worker/... となるのは、tsconfig.worker.json が rootDir を src に設定しており、エントリーポイントが src/worker/index-worker.ts にあるためです。

LLM エージェント向け

エージェントの詳細な手順については、このリポジトリの SKILL.md をお読みください。

開発

Node.js 20 以降が必要です。

npm install
npm run build

# Dev (tsx, no build step)
npm run dev              # MCP stdio (default)
npm run dev:mcp:http     # MCP HTTP
npm run dev -- docs index --section "SERP API"   # CLI

# After build
npm run start            # MCP stdio (default)
npm run start:mcp:http   # Streamable HTTP
npx . docs index --list-sections