DataForSEO MCP Server

This is the new v3 MCP server. The previous v2+ MCP server is deprecated and lives at dataforseo/mcp-server-typescript-deprecated.

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.

Quick Start

Start the MCP server on stdio (default mode; set DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD):

bashCopy code
npx dataforseo-mcp-server@latest

HTTP transport (port 3000; override with PORT):

bashCopy code
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.

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

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

cmdCopy code
REM CMD
set DATAFORSEO_LOGIN=your_api_login
set DATAFORSEO_PASSWORD=your_api_password

DATAFORSEO_USERNAME is accepted as an alias for DATAFORSEO_LOGIN. Get API keys at https://app.dataforseo.com/api-access.

MCP Server

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):

bashCopy code
npx dataforseo-mcp-server

MCP HTTP:

bashCopy code
npx dataforseo-mcp-server --mode http

CLI:

bashCopy code
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.

Public remote MCP server URL: https://mcp.dataforseo.com/v3/mcp

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

Local server (default port 3000):

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

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):

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

From the repo root during development:

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

MCP Tools

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:

1. Authorization: Basic header
2. Authorization: Bearer header (OAuth access token)
3. 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

From a built local clone you can also use npx . instead of npx dataforseo-mcp-server.

Examples

bashCopy code
# 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"}]'

Documentation responses are cached for 24 hours. Default cache directory:

• Windows: %LOCALAPPDATA%\dataforseo-mcp-server\docs-cache
• macOS: ~/Library/Caches/dataforseo-mcp-server/docs-cache
• Linux: ~/.cache/dataforseo-mcp-server/docs-cache (or $XDG_CACHE_HOME)

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.

bashCopy code
# 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

Or set env:

• FIELD_CONFIG_PATH — path to a JSON file (Node)
• FIELD_CONFIG_JSON — inline JSON string (Node / Cloudflare Worker)

Minimal example (see field-config.example.json for a fuller sample):

jsonCopy code
{
  "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"]
  }
}

Behavior:

• 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:

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

Architecture

Copy code
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)

Build outputs

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+.

bashCopy code
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