DataForSEO through the v3 MCP server
The plugin runs dataforseo-mcp-server@3. It exposes four tools, not one tool per endpoint. Every DataForSEO endpoint is reached through a single request tool, and the documentation is searchable from the same server.
| Tool |
What it does |
Cost |
docs_list_sections |
Lists the 13 documentation sections: SERP, AI Optimization, Keywords Data, Domain Analytics, Labs, OnPage, Backlinks, Content Analysis, Merchant, App Data, Business Data, Databases, Appendix |
free |
docs_index |
Lists the endpoints of one section ({section: "SERP API"}) or of all |
free |
docs_search |
Returns the documentation page of one endpoint: fields, limits, Pricing link, example (needCodeExample: true adds PHP, Node.js, Python, C#) |
free, cached 24 hours |
api_request |
Sends an authenticated request to the DataForSEO API |
paid |
Claude Code names each tool with the plugin server prefix, for example mcp__plugin_dataforseo-dev_dataforseo__api_request; the rest of this plugin uses the short names api_request, docs_search, docs_index and docs_list_sections. The old per-endpoint tools of the v2 server (dataforseo_labs_google_keyword_ideas, backlinks_summary and the rest) no longer exist; a call to one of them fails with "tool not found".
The docs-first cycle
Follow it for every endpoint the first time it is used in a session.
- Find the endpoint. Look in references/endpoint-paths.md first. If the task is not there,
docs_list_sections() then docs_index({section: "<name>"}).
- Read its page.
docs_search({url: "dataforseo_labs/google/keyword_ideas/live"}). Add needCodeExample: true only when the body shape is unclear. Note the required fields, the limits and the Pricing link. Free.
- Agree the budget. State the calls you plan, with their
limit and depth, and get the user's go-ahead. See the cost-awareness skill. No api_request before this.
- Send the request. One call, then read
status_code and items before planning the next call.
docs_search({url: "serp/google/organic/live/advanced"})
api_request({
method: "POST",
path: "/v3/serp/google/organic/live/advanced",
data: [{"keyword": "best crm software", "location_code": 2840, "language_code": "en", "depth": 10}]
})
Shape of an api_request
| Field |
Meaning |
method |
POST for every Live endpoint; GET for location, language, model and account lookups |
path |
The REST path, starting /v3/, without a host and without .ai |
data |
The body. For a Live endpoint an array with exactly one task object |
noAiMode |
true returns the full response instead of the trimmed one; default false |
url |
A full URL instead of path; leave it alone unless the user asks |
A Live endpoint takes one task per request. To cover many keywords or targets, use the endpoint's own array field (keywords, targets), not several tasks.
.ai mode and noAiMode
By default the server appends .ai to the path. DataForSEO then returns a cropped response: the envelope shrinks to id, status_code and status_message; empty, null and false fields are dropped; floats are rounded to three places; position and xpath are removed; monthly_searches becomes {"2025-03": 201000, ...}; and limit and depth default to 10 where the endpoint accepts them. It costs the same as the full response.
- Set
limit or depth explicitly whenever you want more than 10 rows.
- The cropped form is documented for Live and Task GET endpoints. If a lookup or an Appendix path is rejected, retry it once with
noAiMode: true.
- The
cost field is not in the cropped envelope. To see what a call cost, read the balance before and after (GET /v3/appendix/user_data with noAiMode: true, free) or send that one call with noAiMode: true.
- Use
noAiMode: true only when a field you need is missing from the cropped answer. It can multiply the context size.
- The server can also trim responses per endpoint through a field-config file (
--configuration, or the FIELD_CONFIG_PATH or FIELD_CONFIG_JSON environment variable), keyed by endpoint path such as /v3/backlinks/summary/live. It is off in this plugin, except for a built-in trim of the Lighthouse payload.
Pick the endpoint
The full table with a minimal body per row is references/endpoint-paths.md. The short version:
| Task |
Endpoint family |
| Keyword ideas, volume, difficulty, intent |
Labs keyword_ideas, keyword_overview, bulk_keyword_difficulty, search_intent |
| What a competitor ranks for, who competes |
Labs ranked_keywords, competitors_domain, domain_intersection |
| The live SERP for a keyword |
SERP google/organic/live/advanced |
| Backlink profile, spam, link gaps |
Backlinks summary, referring_domains, bulk_spam_score, domain_intersection |
| Page audit, tech stack |
OnPage lighthouse, instant_pages; Domain Analytics domain_technologies |
| Web mentions and sentiment |
Content Analysis search, summary, phrase_trends |
| Brand visibility in ChatGPT and Google AI |
AI Optimization llm_mentions/*, chat_gpt/llm_scraper (the ai-optimization skill) |
| Amazon, app stores, local businesses |
Merchant, App Data, Business Data |
Parameters that appear everywhere
| Parameter |
Description |
location_code or location_name |
One of the two. 2840 is United States. Look codes up with the GET location endpoints |
language_code or language_name |
"en" for English. ChatGPT data in AI Optimization is United States and English only |
limit, offset |
Rows to return and rows to skip; limit is 10 in .ai mode unless set, 1000 at most |
filters |
[["field", "operator", value], "and", ["field2", "operator", value2]] |
order_by |
["field,desc"]; at most three rules |
tag |
Your own label, echoed back in the response data |
Filter operators: =, <>, >, <, >=, <=, like, not_like, in, not_in, and on some endpoints regex, ilike, match. Field names differ per API; docs_search({url: "dataforseo_labs/filters"}) and its siblings list them.
Reading the answer
status_code: 20000 is success. 40000 and up is a client error, 50000 and up a server error; docs_search({url: "appendix/errors"}) has the list.
- The data is in
tasks[].result[], usually in an items array. In .ai mode the envelope is flattened to id, status_code, status_message and items.
- An empty
items array is an answer, not an error: DataForSEO has no data for that query.
- Targets are domains without
https:// and www.; pages are absolute URLs.
Cost
Every api_request is billed, and the plugin never sends one without an agreed budget. The rules and the free balance check are in the cost-awareness skill.
1---2name: mcp-patterns-113description: Use for how to call the DataForSEO MCP server - its tools (api_request, docs_search, docs_index, docs_list_sections), the docs-first cycle, request bodies and the .ai response mode - and to build the right call for an endpoint family without a task skill, such as SERP, Merchant, App Data or Business Data. Not for site audits, content analysis, page parsing, technologies or WHOIS (site-audit).4metadata:5 source: https://skillmd.com/skills/agents-store/mcp-patterns-116---78# DataForSEO through the v3 MCP server910The plugin runs `dataforseo-mcp-server@3`. It exposes **four tools**, not one tool per endpoint. Every DataForSEO endpoint is reached through a single request tool, and the documentation is searchable from the same server.1112| Tool | What it does | Cost |13|---|---|---|14| `docs_list_sections` | Lists the 13 documentation sections: SERP, AI Optimization, Keywords Data, Domain Analytics, Labs, OnPage, Backlinks, Content Analysis, Merchant, App Data, Business Data, Databases, Appendix | free |15| `docs_index` | Lists the endpoints of one section (`{section: "SERP API"}`) or of all | free |16| `docs_search` | Returns the documentation page of one endpoint: fields, limits, Pricing link, example (`needCodeExample: true` adds PHP, Node.js, Python, C#) | free, cached 24 hours |17| `api_request` | Sends an authenticated request to the DataForSEO API | **paid** |1819Claude Code names each tool with the plugin server prefix, for example `mcp__plugin_dataforseo-dev_dataforseo__api_request`; the rest of this plugin uses the short names `api_request`, `docs_search`, `docs_index` and `docs_list_sections`. The old per-endpoint tools of the v2 server (`dataforseo_labs_google_keyword_ideas`, `backlinks_summary` and the rest) no longer exist; a call to one of them fails with "tool not found".2021## The docs-first cycle2223Follow it for every endpoint the first time it is used in a session.24251. **Find the endpoint.** Look in [references/endpoint-paths.md](references/endpoint-paths.md) first. If the task is not there, `docs_list_sections()` then `docs_index({section: "<name>"})`.262. **Read its page.** `docs_search({url: "dataforseo_labs/google/keyword_ideas/live"})`. Add `needCodeExample: true` only when the body shape is unclear. Note the required fields, the limits and the Pricing link. Free.273. **Agree the budget.** State the calls you plan, with their `limit` and `depth`, and get the user's go-ahead. See the `cost-awareness` skill. No `api_request` before this.284. **Send the request.** One call, then read `status_code` and `items` before planning the next call.2930```31docs_search({url: "serp/google/organic/live/advanced"})3233api_request({34 method: "POST",35 path: "/v3/serp/google/organic/live/advanced",36 data: [{"keyword": "best crm software", "location_code": 2840, "language_code": "en", "depth": 10}]37})38```3940## Shape of an `api_request`4142| Field | Meaning |43|---|---|44| `method` | `POST` for every Live endpoint; `GET` for location, language, model and account lookups |45| `path` | The REST path, starting `/v3/`, without a host and without `.ai` |46| `data` | The body. For a Live endpoint an array with exactly one task object |47| `noAiMode` | `true` returns the full response instead of the trimmed one; default `false` |48| `url` | A full URL instead of `path`; leave it alone unless the user asks |4950A Live endpoint takes **one task per request**. To cover many keywords or targets, use the endpoint's own array field (`keywords`, `targets`), not several tasks.5152## `.ai` mode and `noAiMode`5354By default the server appends `.ai` to the path. DataForSEO then returns a cropped response: the envelope shrinks to `id`, `status_code` and `status_message`; empty, `null` and `false` fields are dropped; floats are rounded to three places; `position` and `xpath` are removed; `monthly_searches` becomes `{"2025-03": 201000, ...}`; and `limit` and `depth` **default to 10** where the endpoint accepts them. It costs the same as the full response.5556- Set `limit` or `depth` explicitly whenever you want more than 10 rows.57- The cropped form is documented for Live and Task GET endpoints. If a lookup or an Appendix path is rejected, retry it once with `noAiMode: true`.58- The `cost` field is not in the cropped envelope. To see what a call cost, read the balance before and after (`GET /v3/appendix/user_data` with `noAiMode: true`, free) or send that one call with `noAiMode: true`.59- Use `noAiMode: true` only when a field you need is missing from the cropped answer. It can multiply the context size.60- The server can also trim responses per endpoint through a field-config file (`--configuration`, or the `FIELD_CONFIG_PATH` or `FIELD_CONFIG_JSON` environment variable), keyed by endpoint path such as `/v3/backlinks/summary/live`. It is off in this plugin, except for a built-in trim of the Lighthouse payload.6162## Pick the endpoint6364The full table with a minimal body per row is [references/endpoint-paths.md](references/endpoint-paths.md). The short version:6566| Task | Endpoint family |67|---|---|68| Keyword ideas, volume, difficulty, intent | Labs `keyword_ideas`, `keyword_overview`, `bulk_keyword_difficulty`, `search_intent` |69| What a competitor ranks for, who competes | Labs `ranked_keywords`, `competitors_domain`, `domain_intersection` |70| The live SERP for a keyword | SERP `google/organic/live/advanced` |71| Backlink profile, spam, link gaps | Backlinks `summary`, `referring_domains`, `bulk_spam_score`, `domain_intersection` |72| Page audit, tech stack | OnPage `lighthouse`, `instant_pages`; Domain Analytics `domain_technologies` |73| Web mentions and sentiment | Content Analysis `search`, `summary`, `phrase_trends` |74| Brand visibility in ChatGPT and Google AI | AI Optimization `llm_mentions/*`, `chat_gpt/llm_scraper` (the `ai-optimization` skill) |75| Amazon, app stores, local businesses | Merchant, App Data, Business Data |7677## Parameters that appear everywhere7879| Parameter | Description |80|---|---|81| `location_code` or `location_name` | One of the two. `2840` is United States. Look codes up with the GET location endpoints |82| `language_code` or `language_name` | `"en"` for English. ChatGPT data in AI Optimization is United States and English only |83| `limit`, `offset` | Rows to return and rows to skip; `limit` is 10 in `.ai` mode unless set, 1000 at most |84| `filters` | `[["field", "operator", value], "and", ["field2", "operator", value2]]` |85| `order_by` | `["field,desc"]`; at most three rules |86| `tag` | Your own label, echoed back in the response `data` |8788Filter operators: `=`, `<>`, `>`, `<`, `>=`, `<=`, `like`, `not_like`, `in`, `not_in`, and on some endpoints `regex`, `ilike`, `match`. Field names differ per API; `docs_search({url: "dataforseo_labs/filters"})` and its siblings list them.8990## Reading the answer9192- `status_code: 20000` is success. `40000` and up is a client error, `50000` and up a server error; `docs_search({url: "appendix/errors"})` has the list.93- The data is in `tasks[].result[]`, usually in an `items` array. In `.ai` mode the envelope is flattened to `id`, `status_code`, `status_message` and `items`.94- An empty `items` array is an answer, not an error: DataForSEO has no data for that query.95- Targets are domains **without** `https://` and `www.`; pages are absolute URLs.9697## Cost9899Every `api_request` is billed, and the plugin never sends one without an agreed budget. The rules and the free balance check are in the `cost-awareness` skill.