# dataforseo-mcp-server

An MCP server (stdio) that exposes the [DataForSEO](https://dataforseo.com) SEO API
— SERP, keywords, backlinks, labs, on-page, and more — as tools for Claude Code or
any other MCP client.

## Install

Requires Node.js 20+.

```bash
git clone <this-repo>
cd dataforseo-mcp-server
npm install
npm run build
npm link        # puts the `dataforseo-mcp-server` command on your PATH
```

## Credentials

```bash
cp .env.example .env
```

Then edit `.env`:

```
DATAFORSEO_LOGIN=your_login
DATAFORSEO_PASSWORD=your_password
```

Both come from your DataForSEO account (dashboards → API access page). The server
finds this `.env` no matter which directory it's launched from, so the `.mcp.json`
block needs no `env` entry — and any `DATAFORSEO_LOGIN`/`DATAFORSEO_PASSWORD` set
in the environment still take precedence over `.env`.

## Use with Claude Code

Paste into a project's `.mcp.json`, or into `~/.claude.json` under `mcpServers`
to make it available everywhere:

```json
{
  "mcpServers": {
    "dataforseo": {
      "type": "stdio",
      "command": "dataforseo-mcp-server"
    }
  }
}
```

Restart the session or run `/mcp`. Do not use `"command": "npm", "args": ["start"]"`,
as npm's output corrupts the MCP stream.

## Optional settings (in `.env`)

| Variable | What it does |
|---|---|
| `ENABLED_MODULES` | Expose only some API categories, e.g. `SERP,LABS,BACKLINKS`. Fewer tools = less context used by the LLM |
| `ENABLED_TOOLS` | Expose only specific tools, e.g. `serp_google_maps_live,labs_google_keyword_ideas` |
| `LOCALFALCON_API_KEY` | Optional Local Falcon (local ranking) integration |

If none are set, everything is exposed.

## Troubleshooting

`404` on some tools usually means that DataForSEO module isn't enabled for your
account (subscriptions are per module) — enable it in the DataForSEO dashboard.
It is not a bug in this server.

## Secrets

Never commit `.env` (already gitignored).