setup

# DataForSEO Setup Verification Verify that the DataForSEO MCP server is running and that the credentials work, without spending money. ## Prerequisites - The plugin's `.mcp.json` server, which starts `dataforseo-mcp-server@3` (4 tools: `docs_list_sections`, `docs_index`, `docs_search`, `api_request`) - A DataForSEO account with API access - Node.js 22 or newer (`node --version`); the v3 server does not start on older versions - The API login and API password in the environment (see "Credentials" below) ## Verification Steps ### 1. Check that the server runs ``` docs_list_sections() ``` **Expected result:** 13 section names (SERP API, AI Optimization API, Keywords Data API, Domain Analytics API, DataForSEO Labs API, OnPage API, Backlinks API, Content Analysis API, Merchant API, App Data API, Business Data API, Databases, Appendix). This call is free and needs no credentials, so it proves the server started and nothing else. ### 2. Check that the credentials work ``` api_request({method: "GET", path: "/v3/appendix/user_data", noAiMode: true}) ``` **Expected result:** `status_code` 20000 and your account's `money.balance`. DataForSEO states that this endpoint is not charged. It is the only `api_request` this plugin sends without an agreed budget. ### 3. Read an endpoint page ``` docs_search({url: "dataforseo_labs/google/keyword_overview/live"}) ``` **Expected result:** the documentation page of the endpoint with its fields and Pricing link. Free, cached for 24 hours. ### 4. Common Issues | Symptom | Cause | Fix | |---------|-------|-----| | The tools do not appear | The server did not start | Check `node --version` is 22 or newer; restart Claude Code | | 401 Unauthorized | Wrong credentials | Use the API login and API password, not the account email and password; see "Credentials" | | `npx` error | Package not found | Run `npx -y dataforseo-mcp-server@3` manually to see the error | | A v2 tool name is "not found" | The per-endpoint tools were removed in v3 | Use `api_request` with the endpoint path; see the `mcp-patterns` skill | | Timeout | Network or firewall | Check connectivity to `api.dataforseo.com` | | 402 or empty results | No balance | Check the balance at app.dataforseo.com | ## Credentials The server authenticates with the **API login** and the **API password** from the [API Access](https://app.dataforseo.com/api-access) page. The API password is generated by DataForSEO; it is not the password of your account, and your account password will be rejected. | Variable | Meaning | |----------|---------| | `DATAFORSEO_USERNAME` | The API login. The plugin's `.mcp.json` reads this name; the server accepts it as an alias of `DATAFORSEO_LOGIN` | | `DATAFORSEO_LOGIN` | The same API login under the name the server documents. Use it if you run the server yourself | | `DATAFORSEO_PASSWORD` | The API password | Set `DATAFORSEO_USERNAME` and `DATAFORSEO_PASSWORD` in your environment (or the Claude Code settings `env` block). The values stay out of the plugin files. DataForSEO also offers a hosted remote MCP server with OAuth 2.0, which needs no stored password. You would add it as a separate server of your own. Its tools then take the name you give that server, not this plugin's, so the plugin's commands and agent will not list them as allowed. ## What This Skill Does NOT Cover - Creating a DataForSEO account (see [dataforseo.com](https://dataforseo.com)) - Billing and credit management (see the app.dataforseo.com dashboard) - Spending rules for paid calls (see the `cost-awareness` skill)