MCP server and CLI for LLM agents to browse DataForSEO API documentation and make authenticated API requests. By default the binary starts an MCP server on stdio; CLI commands are an optional second mode.
CLI and MCP server for DataForSEO API — browse documentation and make authenticated API requests
2026-11-16
星數
—
工具
—
可用率
—
Quick Start
Start the MCP server on stdio (default mode; set DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD):
npx dataforseo-mcp-server@latest
HTTP transport (port 3000; override with PORT):
npx dataforseo-mcp-server@latest --mode http
Authentication
OAuth 2.0 (default for HTTP MCP): works out of the box. MCP clients discover the DataForSEO authorization server via Protected Resource metadata and send Authorization: Bearer tokens.
Fallback: API login/password via environment variables (HTTP Basic). Required for CLI and stdio MCP; on HTTP it is used when no Authorization header is present.
# bash / macOS / Linux
export DATAFORSEO_LOGIN="your_api_login"
export DATAFORSEO_PASSWORD="your_api_password"
The same tool implementations power both the MCP server and the CLI. One binary serves both modes; MCP is the default.
How the binary chooses a mode:
MCP stdio — default when no CLI command is passed
MCP HTTP — pass --mode http (Streamable HTTP on port 3000; override with PORT)
CLI — when the first command is docs or request, or when --cli / --help / --version is passed
MCP stdio (default):
npx dataforseo-mcp-server
MCP HTTP:
npx dataforseo-mcp-server --mode http
CLI:
npx dataforseo-mcp-server docs index
MCP client config (Cursor, Claude Desktop, and similar clients that use mcpServers):
Via URL — use the hosted remote MCP server, or start a local HTTP server (npx dataforseo-mcp-server --mode http) and point the client at it. OAuth works out of the box; env credentials are optional fallback only.
Via command (stdio) — the client starts the binary itself (stdio is the default mode). OAuth is not used on this transport — set env credentials (or pass them in the MCP client env block):
Fetch documentation index, optionally filtered by section (24h cache)
docs_list_sections
Docs List Sections
Return available documentation section names
docs_search
Docs Search
Fetch documentation from a documentation URL (needCodeExample, 24h cache)
api_request
API Request
Make an authenticated API request
api_request uses .ai paths by default. Set noAiMode to true in MCP requests, or pass --no-ai-mode in the CLI, to use the standard path. Request body is passed as data (JSON object or array). The --param option is CLI-only.
HTTP transport
Streamable HTTP endpoints:
POST /mcp
POST /http
OAuth 2.0 Protected Resource metadata (RFC 9728) is always exposed so MCP clients can discover the authorization server and authenticate with Bearer tokens:
GET /.well-known/oauth-protected-resource
GET /.well-known/oauth-protected-resource/mcp
GET /.well-known/oauth-protected-resource/http
Behind a reverse proxy, set TRUST_PROXY=true so metadata URLs use https.
Auth priority on HTTP requests:
Authorization: Basic header
Authorization: Bearer header (OAuth access token)
Env credentials (DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD) — fallback when no Authorization header is sent
CLI (optional)
In addition to MCP, the same binary exposes docs and request as CLI commands.
Commands
Command
Description
npx dataforseo-mcp-server docs index
Fetch full API documentation index
npx dataforseo-mcp-server docs index --section "SERP API"
Filter index by API section
npx dataforseo-mcp-server docs index --list-sections
List available sections
npx dataforseo-mcp-server docs search <url>
Fetch documentation from a documentation URL or path (cURL example only by default)
Override with --cache-dir <path> on CLI docs commands. For MCP, pass --docs-cache-dir <path> in server startup args.
API responses are returned as the response body only (parsed JSON when possible). When a field configuration is loaded, api_request / request responses are trimmed to the configured fields for that endpoint path (see Field configuration).
Field configuration
Optionally limit which fields are returned from API responses. Unlike the previous multi-tool MCP server (keys = tool names), this package keys the config by API endpoint path.
# 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
Built-in defaults always apply for /v3/on_page/lighthouse/live/json (shrunk Lighthouse payload). Custom config merges on top and can override any path.
Path match ignores .ai suffix, trailing slash, and host (full URLs work).
If the path is configured with a non-empty field list → only those fields are kept (applied to each tasks[].result[] item).
If the path has an empty field list [] → full response for that path (disables filtering).
If the path is missing from both defaults and custom config → full response.
Copy the example and trim to the endpoints you use:
Worker path is build/worker/worker/... because tsconfig.worker.json sets rootDir to src and the entry lives at src/worker/index-worker.ts.
For LLM Agents
Read SKILL.md in this repo for full agent instructions.
Development
Requires 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