/mcp-server-typescript

name: dataforseo-mcp-server
description: >-
  Run DataForSEO API tasks via the CLI in a shell (docs index, docs search, request).
  Use when the agent should execute terminal commands with npx dataforseo-mcp-server.

DataForSEO MCP Server — LLM Agent Guide

Run shell commands and read stdout/stderr. Always invoke the tool through the terminal — never substitute another integration path.

How AI agents interact with this tool

1. **Invoke via shell** — use the terminal (Shell tool) to run `npx dataforseo-mcp-server …` commands. 2. **Read the output** — successful results are printed to stdout (JSON or documentation text). Errors go to stderr and exit code is non-zero. 3. **Auth for CLI** — set `DATAFORSEO_LOGIN` and `DATAFORSEO_PASSWORD` in the shell environment (fallback / CLI path; see Authentication below).

**Binary name:** `npx dataforseo-mcp-server` (or `npx .` from this repo root after `npm install` + `npm run build`).

**Working directory:** any directory where credentials are available in the environment (for CLI).

---

Authentication

| Mode | Preferred auth | Fallback | | ---- | -------------- | -------- | | MCP stdio (default when no CLI command; or `npx dataforseo-mcp-server` with no args) | Env credentials (HTTP Basic) | — | | HTTP MCP (`--mode http`) | OAuth 2.0 Bearer via authorization server `https://data.dataforseo.com` (discovery at `/.well-known/oauth-protected-resource`) | `DATAFORSEO_LOGIN` + `DATAFORSEO_PASSWORD` in env | | CLI (`docs` / `request` / `--cli`) | Env credentials (HTTP Basic) | — |

Override the authorization server with `AUTH_SERVER_URL` if needed.

---

Quick reference

| Task | Shell command | | ---------------------------------- | --------------------------------------------------------------------------- | | Docs index | `npx dataforseo-mcp-server docs index [--section "SERP API"]` | | List sections | `npx dataforseo-mcp-server docs index --list-sections` | | Endpoint docs | `npx dataforseo-mcp-server docs search <url-or-path>` | | Endpoint docs (with code examples) | `npx dataforseo-mcp-server docs search <url-or-path> --need-code-example` | | GET request | `npx dataforseo-mcp-server request -X GET -p /v3/...` | | POST request | `npx dataforseo-mcp-server request -X POST -p <path> --param key=value ...` | | POST request (JSON) | `npx dataforseo-mcp-server request -X POST -p <path> -d '<json-array>'` |

By default, API paths use the `.ai` suffix (e.g. `/v3/serp/google/organic/live/regular.ai`). Pass `--no-ai-mode` to use the standard path.

**CLI credentials (fallback / shell):** set `DATAFORSEO_LOGIN` and `DATAFORSEO_PASSWORD` as environment variables. Get keys at [https://app.dataforseo.com/api-access](https://app.dataforseo.com/api-access)

export DATAFORSEO_LOGIN=your_api_login
export DATAFORSEO_PASSWORD=your_api_password

Windows PowerShell: `$env:DATAFORSEO_LOGIN="..."` / `$env:DATAFORSEO_PASSWORD="..."`. CMD: `set DATAFORSEO_LOGIN=...`

`DATAFORSEO_USERNAME` is also accepted as an alias for `DATAFORSEO_LOGIN`. For HTTP MCP, prefer OAuth; env credentials are only a fallback when no `Authorization` header is present.

---

Agent workflow (shell)

Run these steps as separate shell commands:

1. `npx dataforseo-mcp-server docs index --section "<API>"` — find endpoint path. 2. `npx dataforseo-mcp-server docs search <path>` — read method, parameters, example body. 3. `npx dataforseo-mcp-server request -X <METHOD> -p <path> --param key=value ...` (or `-d '<json-array>'`) — call API.

Parse the printed output to decide the next step.

---

POST body

POST endpoints accept a **JSON array of task objects**: `[{ ... }]`.

**Preferred:** pass fields with repeatable `--param key=value` (merged into the first task object). Use exact API field names from endpoint docs (e.g. `keyword`, `language_code`, `location_code`).

`--param` values override the same fields in `-d` JSON when both are used.

**Array values** (PowerShell strips `"` inside `[...]`, so prefer these forms):

# single-item array
--param keywords=[phone]

# multiple items (pipe-separated)
--param keywords=[phone|tablet|laptop]

# or repeat the same key
--param keywords=phone --param keywords=tablet

# order_by with comma inside the value
--param order_by=[keyword_info.search_volume,desc]

Valid JSON in `--param` still works when your shell preserves quotes (bash: `'keywords=["phone"]'`).

Example: Live SERP (`/v3/serp/google/organic/live/regular`)

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

JSON form:

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

---

Installation (once per environment)

cd /path/to/mcp-server-typescript
npm install
npm run build
export DATAFORSEO_LOGIN=your_api_login
export DATAFORSEO_PASSWORD=your_api_password
npx dataforseo-mcp-server --help

From a project with CLI as a dependency:

cd /path/to/your-project
npm install
export DATAFORSEO_LOGIN=your_api_login
export DATAFORSEO_PASSWORD=your_api_password
npx dataforseo-mcp-server docs index --list-sections

Dev without build (CLI repo only): `npm run dev -- docs index`

---

Commands reference

docs index

npx dataforseo-mcp-server docs index
npx dataforseo-mcp-server docs index --section "SERP API"
npx dataforseo-mcp-server docs index --list-sections
npx dataforseo-mcp-server docs index --cache-dir D:\my-docs-cache

Sections: SERP API, AI Optimiza