Build an SEO research agent with the DataForSEO MCP server

An SEO research agent answers a narrow question with live data: who currently ranks for this query, and which related queries are worth writing about. It should not invent search volume, and it should not browse a handful of blogs and call that a SERP. DataForSEO publishes both a REST API and an MCP server that can call that API. This tutorial connects the MCP server, then forces the agent to use two specific endpoints so you can check its work.

The catalogue page is the IQ.net record. The button is the affiliate link for DataForSEO. IQ.net is not the API host. Do not send your API password to iq.net, and do not paste it into the chat that is driving the agent.

What the agent is allowed to answer

Give it a seed query and a market. Ask for three outputs and nothing else:

• The organic results for that query, with rank, title, and URL.
• A short list of related queries from a keyword-ideas call.
• A brief you can edit: search intent in one sentence, the gaps you see in the titles, and three headings you might write.

Anything the API response does not contain is left blank. If the ideas call returns a volume field, you may quote that field and name it as DataForSEO's figure. If the field is absent, you do not estimate one. This rule is what keeps the agent from becoming a confident fiction generator.

Location and language have to be explicit. DataForSEO uses numeric location codes. 2840 is the United States. language_code en is English. If you need another market, look up that location code in DataForSEO's documentation rather than guessing. A wrong code is a different country, not a soft error.

Connect the MCP server

DataForSEO documents more than one way to attach the server. Pick one and delete the others so the client is not talking to two accounts.

For an interactive client that can open a browser, their Cursor guide uses the remote endpoint and a sign-in:

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

Save that in the client's MCP config, then use the client's connect button and approve access on the DataForSEO screen. Their product pages also show a versioned URL, https://mcp.dataforseo.com/v3/mcp, including a form that sends a Basic auth header. Use the URL in the guide you are following. If a guide shows both, the OAuth-style URL is the one for a person at the keyboard. The versioned URL with a header is the one for a client that cannot pop a browser.

For a machine that must run unattended, use the local server and environment variables. DataForSEO's current setup pages use DATAFORSEO_USERNAME and DATAFORSEO_PASSWORD. Those values are the API login and API password from the API Access tab of the account, not the password you use to sign into the website, unless the account happens to show the same pair there. Read the labels on the API Access tab.

{
  "mcpServers": {
    "dataforseo": {
      "command": "npx",
      "args": ["-y", "dataforseo-mcp-server"],
      "env": {
        "DATAFORSEO_USERNAME": "your_api_login",
        "DATAFORSEO_PASSWORD": "your_api_password"
      }
    }
  }
}

Node 18 or newer is required by the package. If the process exits immediately and says the login is missing, check the variable names against the README of the version npx just downloaded. Guides have used DATAFORSEO_LOGIN for the same API login. The password variable has stayed DATAFORSEO_PASSWORD. Match the names the running version prints. Do not "fix" a missing variable by pasting the password into the prompt.

After the client reloads, the tool list should include the DataForSEO server. If it does not, the config file is in the wrong directory or the process cannot find npx. Fix that before you write a research prompt. A model with no tool will still answer, and the answer will be from memory.

The IQ.net listing is DataForSEO.

Open DataForSEO

The two calls to insist on

You can let the MCP server choose a path, but then you cannot review it. Name the endpoints in the prompt. Both are live POSTs on the DataForSEO v3 API. The MCP server's job is to perform them with the credentials you configured. The bodies below are also what you would send yourself with HTTP Basic auth, base64(api_login:api_password), if you were debugging without a model in the middle.

Google organic results:

curl -sS -X POST "https://api.dataforseo.com/v3/serp/google/organic/live/advanced" \
  -u "$DATAFORSEO_USERNAME:$DATAFORSEO_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '[{
    "keyword": "mcp servers for seo",
    "location_code": 2840,
    "language_code": "en",
    "depth": 10
  }]'

depth is how many results to collect. Ten is enough to see the first page without pulling a huge payload into the chat. The response is a task object. Organic rows usually include a rank, a title, a URL, and a description. Ignore ads, maps, and other item types unless you asked for them. If status_code on the task is not a success, stop and show that code. Do not invent a top ten.

Keyword ideas for the same seed:

curl -sS -X POST "https://api.dataforseo.com/v3/dataforseo_labs/google/keyword_ideas/live" \
  -u "$DATAFORSEO_USERNAME:$DATAFORSEO_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '[{
    "keywords": ["mcp servers for seo"],
    "location_code": 2840,
    "language_code": "en",
    "limit": 10
  }]'

Each idea is a keyword plus whatever metrics that response includes. Quote a metric only when you can point at the field. A common place for search volume is a nested keyword_info object, but if your payload does not have it, leave the column blank. Do not backfill from another tool and still label the table "DataForSEO."

These two calls cost whatever your DataForSEO account charges for them. This tutorial does not state a price. Check the account before you raise depth or limit, and before you loop the call across hundreds of seeds. An agent with a for-loop and a live SERP endpoint is an easy way to run up a bill. Cap the agent at one seed per user message until you trust it.

The prompt

Paste this after the server is connected. Change the keyword. Leave the rules.

Use the DataForSEO MCP server only. Do not answer from memory.

1. Call the Google organic live advanced endpoint:
   POST /v3/serp/google/organic/live/advanced
   keyword: "mcp servers for seo"
   location_code: 2840
   language_code: en
   depth: 10

2. Call keyword ideas:
   POST /v3/dataforseo_labs/google/keyword_ideas/live
   keywords: ["mcp servers for seo"]
   location_code: 2840
   language_code: en
   limit: 10

Return:
- A table of organic results: rank, title, url. Skip non-organic items.
- A list of related keywords. Include a metric only if the response has that field. Name the field.
- Three observations about the titles, each tied to a URL you listed.
- If a call fails, paste the status and stop.

Do not invent rankings, volumes, or URLs.

Read the tool trace, not just the prose. The trace should show those two endpoints, or the MCP tool names that map onto them. If the model wrote a neat table and the trace is empty, throw the table away. Ask it to call the tool. This is the same discipline as any other agent that can sound right without looking.

When the table is real, sanity-check three rows. Open the URLs. A result that 404s, or a title that does not match the page, means you are reading the wrong part of the JSON, often a raw item or a previous task. Go back to the items array on the successful task and take type equal to organic.

Turn the output into a brief

The agent should stop at a brief you can edit. A useful brief is short because you are about to write the page yourself, or hand a tighter prompt to a drafting model that is not allowed to "do more research."

Use this outline and fill it only from the two responses:

Seed: mcp servers for seo
Market: United States, English (location_code 2840)

What ranks:
- (rank) title — url

Related queries, quoted only when present:
- keyword — metric field: value

Intent, one sentence:
People who search this are trying to ____.

Gaps in the current titles:
- 

Headings worth drafting:
1.
2.
3.

Sources: DataForSEO Google organic live advanced, and DataForSEO Labs keyword ideas, pulled on (date).

The date matters. A SERP is a snapshot. Put the date in the brief so nobody treats last month's top ten as a permanent fact. If you run the same seed next week, keep both briefs. The diff is the interesting part, not a blended average the model writes to be helpful.

Do not ask this agent to publish the page, to build links, or to rewrite someone else's ranking URL. Those are different jobs. This one ends when the brief exists and every URL in it was in the API response.

When the connection is wrong

• The client says the server needs authentication. Finish the browser approval, or set the username and password variables. An empty env block is not "public access."
• The tool runs and the task status is an authorization error. The API login and password are rejected. Copy them again from the API Access tab. Website login and API login are not always the same pair.
• Results are for the wrong country. location_code was omitted and a default was applied, or you used a code for a city when you wanted a country. Set the code in the prompt every time.
• The keyword list is huge. You raised limit or you let the model paginate. Put the limit back to 10 until the brief is good.
• The model calls a different SEO endpoint you did not name. Tell it to stop and use only the two paths above. Extra endpoints are extra charges and a response shape you are not reading carefully.
• Secrets in the chat. Rotate the API password in the DataForSEO account, then put the new value only in the MCP env or the client's secret store.

If you want the fetch to happen on a schedule rather than in a chat, call the same two URLs from a small script using the curl above, write the JSON to disk, and only then ask a model to fill the brief from those files. That split is easier to audit. The MCP setup is the right one when a person is in the loop asking follow-up questions about a seed. The script is the right one when fifty seeds run every Monday.

The listing to open first is DataForSEO on IQ.net. For a different kind of web access, the Firecrawl guide is about reading a page you already have a URL for. This one is about the search results and the related queries, not about scraping the pages that rank. Read those pages separately, and only the ones you choose from the table.

Open DataForSEO