# mcp-server-seoradar

MCP server for [SEO Radar](https://seoradar.cz) — run SEO audits and manage URL monitoring from any MCP-compatible AI client.

## Prerequisites

- Node.js ≥ 20
- An `sr_live_` API key from [seoradar.cz](https://seoradar.cz)

## Quick install

Add to your MCP client config:

```json
{
  "mcpServers": {
    "seoradar": {
      "command": "npx",
      "args": ["-y", "mcp-server-seoradar"],
      "env": { "SEORADAR_API_KEY": "sr_live_your_key_here" }
    }
  }
}
```

## Setup

### Claude Code

```bash
claude mcp add seoradar -e SEORADAR_API_KEY=sr_live_your_key -- npx -y mcp-server-seoradar
```

### Claude Desktop

Config file: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "seoradar": {
      "command": "npx",
      "args": ["-y", "mcp-server-seoradar"],
      "env": { "SEORADAR_API_KEY": "sr_live_your_key_here" }
    }
  }
}
```

### Cursor

Config file: `~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "seoradar": {
      "command": "npx",
      "args": ["-y", "mcp-server-seoradar"],
      "env": { "SEORADAR_API_KEY": "sr_live_your_key_here" }
    }
  }
}
```

### VS Code

Config file: `~/.vscode/mcp.json` (or workspace `.vscode/mcp.json`)

```json
{
  "servers": {
    "seoradar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-seoradar"],
      "env": { "SEORADAR_API_KEY": "sr_live_your_key_here" }
    }
  }
}
```

## Available tools

| Tool | Input | Purpose |
| --- | --- | --- |
| `seo_audit` | `{ url }` | Run an audit, return score + summary |
| `get_audit_results` | `{ hash }` | Full per-check report |
| `check_api_usage` | — | Quota: tier/limit/used/remaining |
| `list_monitored_urls` | — | List watched URLs + status |
| `add_monitored_url` | `{ url, label?, cadence? }` | Add a URL to monitoring |
| `get_monitoring_status` | `{ id }` | One URL's latest status |
| `remove_monitored_url` | `{ id }` | Stop watching a URL |

## Usage examples

```
Run an SEO audit on https://example.com
What are the detailed results for audit hash abc123?
How many audits do I have left today?
Show me all my monitored URLs
Add https://example.com to monitoring with label "Homepage" checked daily
What's the latest status of monitored URL 42?
Remove monitored URL 42
```

## Development

```bash
npm install       # install dependencies
npm run build     # compile TypeScript → dist/
npm test          # run vitest tests
npm run lint      # eslint src/
```

## Configuration

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `SEORADAR_API_KEY` | Yes | — | Your `sr_live_` API key from seoradar.cz |
| `SEORADAR_API_URL` | No | `https://seoradar.cz/api/v1` | API base URL (override for staging) |

## Error handling

All tools return structured error messages. Common cases:

- **401** — invalid or missing API key
- **404** — audit hash or monitored URL ID not found
- **422** — invalid URL format or unsupported cadence value
- **429** — rate limit or daily quota exceeded
- **5xx** — SEO Radar API temporarily unavailable

Polling tools (`seo_audit`) retry automatically for up to ~90 s before returning a timeout error.

## Security

The API key is passed via environment variable and never logged or included in responses. Store your key in your OS keychain or a secrets manager — never commit it to source control.

## License

MIT — see [LICENSE](./LICENSE).