DataForSEO MCP Server

A Model Context Protocol (MCP) server that exposes DataForSEO's Research Toolkit API to Claude Desktop. This server automatically generates MCP tools from DataForSEO's OpenAPI specification, allowing Claude to perform SEO research tasks like keyword analysis, SERP data retrieval, and competitor analysis.

Overview

This project uses the adapter library to automatically convert OpenAPI specifications into MCP-compatible tools. The adapter library handles:

• Loading and parsing OpenAPI specifications
• Normalizing API endpoints to a canonical format
• Generating MCP tool definitions
• Managing authentication (automatically filters auth parameters)
• Executing API calls with proper error handling and retries

Project Structure

Core Files

generate_registry.py

This script generates the MCP tool registry from DataForSEO's OpenAPI specification. It:

1. Loads the OpenAPI spec from DataForSEO's GitHub repository
2. Normalizes endpoints to a canonical format using the adapter library
3. Generates MCP tools with automatic auth parameter filtering
4. Exports two files:
   • dataforseo_researcher_toolkit.json - MCP tool registry
   • dataforseo_researcher_endpoints.json - Canonical endpoint definitions

When to run: Run this once initially, or whenever you want to update the tools from the latest OpenAPI spec.

python generate_registry.py

run_server.py

This is the MCP server that Claude Desktop connects to. It:

1. Loads credentials from environment variables (.env file)
2. Loads the tool registry and endpoint definitions
3. Sets up API executor with Basic Auth for DataForSEO
4. Starts the MCP server that communicates with Claude via JSON-RPC

When to run: This runs automatically when Claude Desktop starts (configured in Claude's settings).

Setup

1. Install Dependencies

Create a virtual environment and install required packages:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Configure Credentials

Copy the example environment file and add your DataForSEO credentials:

cp .env.example .env

Edit .env and add your credentials:

DATAFORSEO_USERNAME=your_username_here
DATAFORSEO_PASSWORD=your_password_here

3. Generate the Registry

Run the registry generator to create MCP tools from the OpenAPI spec:

python generate_registry.py

This will create two files:

• dataforseo_researcher_toolkit.json
• dataforseo_researcher_endpoints.json

4. Test the Server

Before configuring Claude Desktop, test that the server runs correctly:

python run_server.py

If everything is configured correctly, you'll see output like:

2025-11-20 10:30:00 - __main__ - INFO - ======================================================================
2025-11-20 10:30:00 - __main__ - INFO - DataForSEO API MCP Server
2025-11-20 10:30:00 - __main__ - INFO - ======================================================================
2025-11-20 10:30:00 - __main__ - INFO - Credentials loaded
2025-11-20 10:30:00 - __main__ - INFO -   Base URL: https://api.dataforseo.com
2025-11-20 10:30:00 - __main__ - INFO - 1. Loading registry from /path/to/dataforseo_researcher_toolkit.json...
2025-11-20 10:30:00 - __main__ - INFO - Loaded 10 tools
2025-11-20 10:30:00 - __main__ - INFO - 2. Loading endpoints from /path/to/dataforseo_researcher_endpoints.json...
2025-11-20 10:30:00 - __main__ - INFO - Loaded 10 endpoints
2025-11-20 10:30:00 - __main__ - INFO - 3. Setting up API executor...
2025-11-20 10:30:00 - __main__ - INFO - Authentication: Basic Auth
2025-11-20 10:30:00 - __main__ - INFO - 4. Creating MCP server...
2025-11-20 10:30:00 - __main__ - INFO - ======================================================================
2025-11-20 10:30:00 - __main__ - INFO - Server ready!
2025-11-20 10:30:00 - __main__ - INFO - ======================================================================
2025-11-20 10:30:00 - __main__ - INFO - Configure in Claude Desktop:
2025-11-20 10:30:00 - __main__ - INFO - {
2025-11-20 10:30:00 - __main__ - INFO -   "mcpServers": {
2025-11-20 10:30:00 - __main__ - INFO -     "dataforseo": {
2025-11-20 10:30:00 - __main__ - INFO -       "command": "/path/to/.venv/bin/python",
2025-11-20 10:30:00 - __main__ - INFO -       "args": ["/path/to/run_server.py"]
2025-11-20 10:30:00 - __main__ - INFO -     }
2025-11-20 10:30:00 - __main__ - INFO -   }
2025-11-20 10:30:00 - __main__ - INFO - }
2025-11-20 10:30:00 - __main__ - INFO - ======================================================================
2025-11-20 10:30:00 - __main__ - INFO - Starting server...

Copy the configuration shown in the output - it will have the correct paths for your system!

Press Ctrl+C to stop the test server.

5. Configure Claude Desktop

Open your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server configuration (use the exact paths shown when you ran the server):

{
  "mcpServers": {
    "dataforseo": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/run_server.py"]
    }
  }
}

Important: Use the absolute paths shown in your test run output, not the example paths above!

6. Restart Claude Desktop

Restart Claude Desktop for the changes to take effect. The DataForSEO tools should now be available in Claude.

How It Works

Using the Adapter Library

This project demonstrates how to use the adapter library to create MCP servers from OpenAPI specifications:

# 1. Load OpenAPI spec
from adapter import OpenAPILoader, Normalizer, ToolGenerator, ToolRegistry

loader = OpenAPILoader()
spec = loader.load("url-to-openapi-spec")

# 2. Normalize to canonical format
normalizer = Normalizer()
endpoints = normalizer.normalize_openapi(spec)

# 3. Generate MCP tools (auth params auto-filtered!)
generator = ToolGenerator()
tools = generator.generate_tools(endpoints)

# 4. Create tool registry
registry = ToolRegistry(name="my_toolkit")
registry.add_tools(tools)

Running the Server

The server uses the MCPServer class from the adapter library:

from adapter import MCPServer, APIExecutor, BasicAuth

# Set up authentication
auth = BasicAuth(username="user", password="pass")

# Create API executor
executor = APIExecutor(
    base_url="https://api.example.com",
    auth=auth,
    timeout=30,
    max_retries=3
)

# Create and run MCP server
server = MCPServer(
    name="My API",
    version="1.0.0",
    tool_registry=registry,
    executor=executor,
    endpoints=endpoints
)

server.run()

Logging

Both scripts use Python's logging module to output to stderr (MCP uses stdout for JSON-RPC communication). You can see the server logs in Claude Desktop's developer console or when running the server manually.

Troubleshooting

Registry files not found

• Make sure you've run generate_registry.py first
• Check that both JSON files were created in the project directory

No credentials found

• Verify your .env file exists and contains valid credentials
• Check that environment variables are set correctly

Server won't start in Claude

• Test the server manually first with python run_server.py
• Verify the paths in your Claude Desktop config are absolute paths
• Check Claude Desktop's logs for error messages

Environment Variables

• DATAFORSEO_USERNAME - Your DataForSEO API username (required)
• DATAFORSEO_PASSWORD - Your DataForSEO API password (required)
• DATAFORSEO_BASE_URL - Override the API base URL (optional, defaults to https://api.dataforseo.com)

Files Generated

• dataforseo_researcher_toolkit.json - MCP tool registry with all available tools
• dataforseo_researcher_endpoints.json - Normalized endpoint definitions used by the executor
• .env - Your credentials (git-ignored)

License

MIT License - Copyright (c) 2025 Pawneet Singh

See the LICENSE file for full license text.

This project uses the REST-to-MCP adapter framework. Refer to the adapter's license for terms and conditions.

This project uses the DataForSEO API. Make sure you have appropriate API credentials and follow DataForSEO's terms of service.