# RankJot MCP server

Real Google rankings as a tool for AI assistants. Ask Claude (or any MCP client)
"where does example.com rank for *best running shoes* in the UK?" and it makes a
live lookup instead of guessing.

<!-- mcp-name: io.github.epolat/rankjot-mcp -->

## What it does

One tool:

**`check_rank(domain, keyword, country="us")`** returns

- `position`: the domain's 1-based Google organic position, or `null` if it isn't
  in the results checked
- `url`: which of the domain's pages ranks
- `results`: the top 10 organic results (position, domain, url, title), so the
  assistant can answer "who's above me?" without another call
- `quota`: lookups used and remaining this month

Positions are organic results only (ads, maps and answer boxes aren't counted),
for the Google market you pass as `country`.

## Setup

**1. Get an API key.** Sign in at [rankjot.com](https://rankjot.com/login), open
**Account → API access → Generate key**. Free accounts include **25 lookups a
month**; the API plan ($20/mo) includes 5,000.

**2. Add the server to your client.** It runs with [`uvx`](https://docs.astral.sh/uv/),
so there's nothing to install by hand.

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "rankjot": {
      "command": "uvx",
      "args": ["rankjot-mcp"],
      "env": { "RANKJOT_API_KEY": "rjk_your_key_here" }
    }
  }
}
```

Any other client that launches stdio servers takes the same command, `uvx
rankjot-mcp`, with `RANKJOT_API_KEY` in its environment.

Prefer pip? `pip install rankjot-mcp`, then use `rankjot-mcp` as the command.

**3. Restart the client** and ask a ranking question.

## Errors

Failures come back as a normal result with an `error` field, so the assistant can
tell you what happened instead of retrying blindly:

| `error` | Meaning |
|---|---|
| `config` | `RANKJOT_API_KEY` isn't set |
| `unauthorized` | The key is wrong or was revoked |
| `api_trial_limit` | This month's included lookups are used up |
| `quota_exceeded` / `rate_limited` | Monthly quota used, or too many calls per minute |
| `provider_error` / `network` | The lookup couldn't be made; try again |

Every call spends one lookup. Models are happy to call tools in loops, so if you
ask about many keywords at once, say how many lookups it may use.

## Privacy

The domain, keyword and country you check are sent to rankjot.com to perform the
lookup. See the [privacy policy](https://rankjot.com/privacy).

## Links

- API reference: https://rankjot.com/api-docs
- How this server was designed: https://rankjot.com/blog/google-rankings-as-an-mcp-tool

## License

MIT