Troubleshoot

Troubleshoot

Diagnose and fix common problems with DataForSEO MCP tools — connection failures, authentication errors, parameter mistakes, empty results, and cost management.

Quick Diagnostics

When something is not working, run this sequence to isolate the problem:

Step 1 — Connectivity Test

Tool: serp_locations
Input: {
  "country_iso_code": "US"
}

This is the lightest DataForSEO call. If it returns location data, the MCP server is running and authenticated. If it fails, the problem is connection or auth.

Step 2 — Check the Error

• No response / timeout → MCP server is not running. See "MCP Server Startup Issues" below.
• 401 Unauthorized → Wrong credentials. See "Authentication Errors" below.
• 400 Bad Request → Invalid parameters. See "Parameter Errors" below.
• 500 Internal Server Error → DataForSEO server issue. See "When to Escalate" below.

Step 3 — Verify Tool Name

DataForSEO MCP exposes 70+ tools. Confirm you are calling the correct tool name. Tool names follow a pattern: {api_group}_{endpoint} (e.g., backlinks_summary, on_page_lighthouse, serp_organic_live_advanced). If a tool is not found, the MCP server may be an older version — see "MCP Server Startup Issues" for update instructions.

Authentication Errors

DataForSEO uses username and password (not API keys). These are set as environment variables in the MCP configuration.

The .mcp.json should contain:

{
  "mcpServers": {
    "dataforseo": {
      "command": "npx",
      "args": ["-y", "dataforseo-mcp-server@latest"],
      "env": {
        "DATAFORSEO_USERNAME": "${DATAFORSEO_USERNAME}",
        "DATAFORSEO_PASSWORD": "${DATAFORSEO_PASSWORD}"
      }
    }
  }
}

The ${DATAFORSEO_USERNAME} and ${DATAFORSEO_PASSWORD} placeholders are resolved from your environment. Verify these are set in your shell profile or Claude Desktop settings.

MCP Server Startup Issues

To verify Node.js version: node --version (must be >= v20).

Parameter Errors

Location Names

Location must be the exact full country name, not an ISO code.

Use serp_locations to find exact location names and codes:

Tool: serp_locations
Input: {
  "country_iso_code": "US"
}

Required Fields

Each tool has required parameters. Common missing fields:

• on_page_lighthouse requires url
• backlinks_summary requires target (domain or URL)
• content_analysis_phrase_trends requires keyword AND date_from
• ai_opt_llm_ment_search requires targets array with at least one object

Filter Syntax

DataForSEO uses a specific filter format: ["field", "operator", "value"]. Nested filters use arrays of arrays. Check available filters per endpoint:

Tool: backlinks_available_filters
Input: {}

Tool: dataforseo_labs_available_filters
Input: {}

Tool: ai_optimization_llm_mentions_filters
Input: {}

Empty Results

Empty results are NOT errors. They mean DataForSEO has no data for that query — which is itself valuable information (your keyword may be too niche or your domain too new).

Cost Model

DataForSEO charges per API call, not by rate limits or monthly subscriptions (though minimums may apply). Each MCP tool call translates to one or more API requests.

Key cost facts:

• Every tool call costs credits. Be intentional — do not call tools speculatively.
• Different endpoints have different costs. Lighthouse and SERP scraping cost more than keyword data.
• Bulk endpoints are cheaper per-unit than individual calls (e.g., backlinks_bulk_ranks vs. calling backlinks_summary in a loop).
• Monitor usage at app.dataforseo.com under Account > API Usage.
• Set budget alerts in the DataForSEO dashboard to avoid unexpected charges.

Common Error Codes

When to Escalate

• Persistent 500 errors → Check DataForSEO status page. If the service is up, contact DataForSEO support with the request payload and error response.
• Data seems wrong → Compare DataForSEO results with a manual Google search for the same query in the same location. Note that DataForSEO data may lag by hours or days.
• MCP server crashes repeatedly → Check Node.js version (node --version must be >= v20). Try npx clear-npx-cache and restart. If it persists, check the npm package page for known issues.
• Tool exists in docs but not in MCP → The MCP server may not expose all DataForSEO endpoints. Check the dataforseo-mcp-server npm package documentation for the list of supported tools.
• Account or billing issues → These cannot be resolved through the MCP. Log in at app.dataforseo.com or contact DataForSEO support directly.