SEO

DataForSEO MCP: set up the official server

The DataForSEO MCP server lets AI agents call DataForSEO's APIs for keywords, SERP results, backlinks and on-page crawls. Here is how to set up the v3 server in Claude, Claude Code, ChatGPT and Cursor, run it locally or from the command line, and fix common problems.

Jesse Sibley
By , FounderPublished · Last updated · 10 min read

DataForSEO MCP is DataForSEO's official MCP server. It lets AI agents read DataForSEO's API documentation and call any of its APIs for SEO data: keywords, SERP results, backlinks, domain metrics, on-page crawls and AI optimization data. The current v3 server runs hosted at https://mcp.dataforseo.com/v3/mcp, where you sign in with OAuth, or locally with npx dataforseo-mcp-server@latest. The server is free and open source. You pay DataForSEO per API call, with a $50 minimum payment.

This guide walks through setting up the official server in Claude, Claude Code, ChatGPT and Cursor, running it locally or from the command line, fixing the common problems, and prompts to try.

What is the DataForSEO MCP server?

The DataForSEO MCP server is a bridge between your AI agent and DataForSEO's API. Version 3, the one in the dataforseo/mcp-server-typescript repository, gives your agent four tools instead of one tool per endpoint:

  • docs_index and docs_list_sections: browse DataForSEO's API documentation by section
  • docs_search: read the documentation for one endpoint
  • api_request: make an authenticated request to any endpoint

So the agent looks up the endpoint it needs, reads its parameters, then calls it. That covers every DataForSEO API:

  • Keywords: search volume, difficulty, CPC and related terms
  • SERP: live Google results for any keyword, location and device
  • Backlinks: backlink profiles, referring domains and anchors
  • Domain metrics: domain rank, organic traffic estimates and ranked keywords
  • On-page: crawls and on-page checks
  • AI optimization: what ChatGPT, Claude, Gemini and Perplexity answer for a prompt
  • Business data: reviews, local listings and business information

By default api_request uses DataForSEO's .ai endpoint paths, which return responses shaped for AI agents.

Diagram: the hosted DataForSEO server against the local server and where each keeps your API login
The two ways to run it. Both spend from the same DataForSEO balance.

Step 1: get a DataForSEO account

Sign up at dataforseo.com if you do not have an account. DataForSEO gives new accounts a $1 trial credit, then requires a $50 minimum payment, and the funds stay on your balance until you spend them (checked October 2026).

With the hosted server you sign in with OAuth and never handle a password. For the local server, or a client that cannot do OAuth, go to the API Access dashboard and copy your API login and API password. These are different from your dashboard login. For a Basic auth header, encode your_api_login:your_api_password in Base64, or use the "Send by Email" button on the API Access page, which sends a pre-encoded token.

How to connect DataForSEO MCP to Claude

Open Claude, go to Customize → Connectors, click Add custom connector, and paste https://mcp.dataforseo.com/v3/mcp. Sign in to DataForSEO and approve the OAuth request when prompted.

DataForSEO MCP in Claude Code

Add the hosted server, then run /mcp in Claude Code and authenticate it to start the OAuth sign-in:

Terminal
claude mcp add --transport http dataforseo https://mcp.dataforseo.com/v3/mcp

If you would rather not use OAuth, pass your Base64 token as a header, the way DataForSEO's Claude Code guide does:

Terminal
claude mcp add --transport http dataforseo https://mcp.dataforseo.com/v3/mcp \
  --header "Authorization: Basic <your_base64_token>"

Or run the server locally over stdio with your API login and password:

Terminal
claude mcp add dataforseo \
  --env DATAFORSEO_LOGIN=your_api_login \
  --env DATAFORSEO_PASSWORD=your_api_password \
  -- npx -y dataforseo-mcp-server@latest

How to connect DataForSEO MCP to ChatGPT

In ChatGPT, custom MCP servers are added in developer mode: go to Settings → Apps → Advanced settings, turn on Developer mode, click Create app, enter https://mcp.dataforseo.com/v3/mcp and choose OAuth.

DataForSEO's own ChatGPT guide covers the OpenAI Platform dashboard instead, for building with the API:

  1. Log in to your OpenAI API account and open the Dashboard
  2. Create a new chat with your preferred model
  3. Click Tools → MCP Server → Add new
  4. Paste the server URL and add a label such as "DataForSEO"
  5. For authentication, choose Custom headers, set the header to Authorization and the value to Basic followed by your Base64 token
  6. Click Connect, then choose which tools to enable and the approval settings

DataForSEO MCP in Cursor

In Settings → Cursor Settings → Tools & MCP, add the hosted server. Cursor starts the OAuth sign-in:

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

To skip OAuth, add a headers block with "Authorization": "Basic <your_base64_token>".

Run it locally

The local server needs Node.js 20 or later, according to the README. Start it over stdio, the default:

Terminal
npx dataforseo-mcp-server@latest

Or over HTTP on port 3000, then point your client at http://localhost:3000/mcp:

Terminal
npx dataforseo-mcp-server@latest --mode http

Locally, set your API login and password as DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD (DATAFORSEO_USERNAME also works for the login). DataForSEO also publishes a Docker image, dataforseo/mcp:latest, which serves the same thing on port 3000. Its MCP page has configs for Claude Desktop, Cursor, Gemini CLI and Docker.

The DataForSEO CLI

The same package is also a command line tool, which is handy for scripts or for checking an endpoint before you ask your agent:

Terminal
npx dataforseo-mcp-server docs index --section "SERP API"
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

It reads the same DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD environment variables.

DataForSEO in Codex

On October 6, 2026, DataForSEO announced a plugin for Codex. It connects Codex in the ChatGPT desktop app and the Codex CLI to the hosted MCP server with your DataForSEO account, so there is no MCP config to write.

Common problems and fixes

Authentication errors

Error: "You are not authorized to access this resource"

Cause: wrong credentials or the wrong credential format.

Fix:

  1. On the hosted server, use OAuth if your client supports it, and finish the sign-in.
  2. Otherwise use your API credentials from the API Access dashboard, not your dashboard login.
  3. Check the format your client expects:
    • Remote HTTP with Basic auth: Base64-encoded login:password
    • Local stdio: plain DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD environment variables

Your tool list looks different, or tools fail with schema errors

Cause: you are on the old v2 server. DataForSEO has deprecated it. It exposed one tool per endpoint, filtered with ENABLED_MODULES, and some clients rejected its schemas.

Fix: move to the v3 server: point your client at https://mcp.dataforseo.com/v3/mcp, or run npx dataforseo-mcp-server@latest. With v3's four tools, client caps on tool counts stop being a problem.

Responses are too large

Cause: some endpoints return hundreds of results per call, and the agent's context window fills up.

Fix:

  1. Ask for fewer results with the endpoint's limit and offset parameters.
  2. Use narrower queries: a specific domain, keyword, location or date range.
  3. On a local server, load a field configuration with --configuration field-config.json or the FIELD_CONFIG_PATH environment variable, which trims each endpoint's response to the fields you list. The README has an example file.

"Fetch is not defined"

Cause: an old Node.js version.

Fix: upgrade to Node.js 20 or later.

Example prompts

Here are prompts to try once the server is connected.

Keyword research

"Find 20 keywords related to 'crm for startups' with at least 200 monthly searches in the US. Show volume, KD, and CPC for each."

Rank check

"Check where example.com ranks on Google US desktop for 'project management software' and 'best project management tools'."

"Show the top 20 referring domains linking to competitor.com, sorted by domain rank. Include anchor text distribution."

Domain overview

"Analyze example.com: domain rank, estimated organic traffic, number of ranked keywords, and top 10 keywords by traffic."

Technical audit

"Crawl example.com and report broken links, missing meta descriptions, slow pages, and duplicate content issues."

AI visibility

"Check whether ChatGPT, Claude, and Gemini recommend my brand for 'best CRM for agencies'. List competitors they mention and which sources they cite."

Run this in your agent

Connect Manifold to Claude, ChatGPT or Cursor, then paste this prompt.

Find keywords where we rank 5 to 15 that could reach page one. For each, show who holds the top three spots and what their pages cover.

Without a DataForSEO account

DataForSEO MCP is the right choice when you want raw access to every DataForSEO endpoint and are happy to hold your own account and balance. If you would rather not, Manifold runs on DataForSEO's data with no DataForSEO account, no deposit and no API keys of your own: you sign in with OAuth and pay per call from credits. It also puts Search Console, Bing Webmaster Tools, social, Reddit, ad libraries and leads in the same server. The SEO numbers are the same, because both use DataForSEO.

For the side by side, read hosted DataForSEO MCP. To compare every SEO MCP server, including the official ones from Ahrefs and Semrush, read the best SEO MCP servers. For those vendors' own servers, see the Ahrefs MCP setup guide and the Semrush MCP setup guide. For parsed results from Google, Bing, YouTube, Amazon and other engines, see the SerpApi MCP setup guide.

Questions people ask

Is the DataForSEO MCP server free?

The MCP server itself is free and open source. You pay DataForSEO for API calls, and prices vary by endpoint. The minimum payment is $50, funds stay on your balance until you spend them, and new accounts get a $1 trial credit to test the API (checked October 2026). See dataforseo.com/pricing for prices by endpoint.

How do I add DataForSEO MCP to Claude Code?

Run claude mcp add --transport http dataforseo https://mcp.dataforseo.com/v3/mcp, then run /mcp in Claude Code and sign in with OAuth. To run it locally instead, use claude mcp add dataforseo --env DATAFORSEO_LOGIN=your_api_login --env DATAFORSEO_PASSWORD=your_api_password -- npx -y dataforseo-mcp-server@latest.

Do I need a DataForSEO account?

Yes. The official server, local or remote, connects to DataForSEO's API with your API credentials, so you need a DataForSEO account. If you do not want one, Manifold is a hosted server with DataForSEO data and no API keys of your own.

What is the difference between API credentials and dashboard login?

Your API credentials (API login and API password) are for making API calls. They are different from the email and password you use to log into the DataForSEO dashboard. Find your API credentials in the API Access dashboard.

Which MCP clients work with DataForSEO?

Any MCP client. The hosted v3 server signs you in with OAuth by default, which works in Claude, Claude Code and Cursor. Clients without OAuth send a Basic auth header to the remote server, or run the local server with environment variables. DataForSEO also has a plugin for Codex.

How do I fix authentication errors?

On the hosted server, use OAuth if your client supports it. Otherwise use your API credentials from the API Access dashboard, not your dashboard login. For remote HTTP, encode credentials as Base64 login:password. For local stdio, set the DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD environment variables.

Why do some tools fail with schema validation errors?

You are most likely on the old v2 server, which DataForSEO has deprecated. It exposed one tool per endpoint, and some clients rejected their schemas. Move to v3: point your client at https://mcp.dataforseo.com/v3/mcp or run npx dataforseo-mcp-server@latest.

Is there a DataForSEO CLI?

Yes. The same npm package is a command line tool: npx dataforseo-mcp-server docs index lists endpoints, and npx dataforseo-mcp-server request -X POST -p followed by an endpoint path makes a call. It uses the DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD environment variables.

Can I run it in Docker?

Yes. DataForSEO's MCP page lists an official image, dataforseo/mcp:latest. Run it with your DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD environment variables and port 3000 published, and the server is available at http://localhost:3000/mcp.

Does it include Search Console or Bing?

No. DataForSEO MCP only covers DataForSEO's own API, which does not include Search Console or Bing Webmaster Tools. If you need Search Console and Bing data, Manifold includes both at 0 credits per call.

Sources

Jesse Sibley

Jesse Sibley

Founder of Manifold. A growth engineer who has worked with London startups for eight years.

All SEO guides