DataForSEO MCP Server

DataForSEO MCP 服务

这是新的 v3 MCP 服务。 之前的 v2+ MCP 服务已弃用，位于 dataforseo/mcp-server-typescript-deprecated。

面向 LLM Agent 的 MCP 服务和命令行工具，可用于浏览 DataForSEO API 文档并发送经过身份验证的 API 请求。默认情况下，二进制文件会通过 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 客户端通过受保护资源元数据发现 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 使用相同的工具实现。一个二进制文件可运行这两种模式；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 受保护资源元数据（RFC 9728），以便 MCP 客户端发现授权服务器并使用 Bearer 令牌进行身份验证：

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

在反向代理后运行时，设置 TRUST_PROXY=true，使元数据 URL 使用 https。

HTTP 请求的身份验证优先级：

1. Authorization: Basic 标头
2. Authorization: Bearer 标头（OAuth 访问令牌）
3. 环境凭据（DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD）— 未发送 Authorization 标头时使用的备用方式

CLI（可选）

除 MCP 外，同一二进制文件还提供 docs 和 request CLI 命令。

命令

命令	说明
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 . 代替 npx dataforseo-mcp-server。

示例

# 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。

面向大模型 Agent

阅读此仓库中的 SKILL.md，了解完整的 Agent 指引。

开发

需要 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