# outrank-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)

MCP server for [Outrank](https://outrank.so), the autonomous SEO content engine built by Tibo Maker. 5 tools for AI agents to verify credits, list managed website products, queue keyword research, generate SEO long-form articles (with optional auto-publish to the connected CMS), and fetch finished article content.

As of May 2026, Outrank does not ship an official MCP server, and no community-built attempt exists. Pure GREEN whitespace.

## The 5 tools

| Tool | Purpose |
|---|---|
| `check_auth_and_credits` | Verify the API key and retrieve remaining article-generation credits |
| `list_products` | List active website products (managed sites) in the organization |
| `generate_keywords` | Queue keyword cluster research for a product on a broad topic |
| `generate_article` | Generate an SEO long-form article targeted at a specific keyword (optional auto-publish) |
| `get_article_content` | Fetch the raw markdown + HTML content for a finished article |

## Install

```bash
pip install outrank-mcp
```

## Configure

```bash
export OUTRANK_API_KEY="outr_live_your-outrank-api-key"
```

Get your API key in your Outrank Dashboard under **Settings -> API keys**. Keys are prefixed `outr_live_`. The MCP sends the key as a Bearer token; keep it server-side only.

## Use with Claude Desktop

```json
{
  "mcpServers": {
    "outrank": {
      "command": "outrank-mcp",
      "env": {
        "OUTRANK_API_KEY": "outr_live_your-outrank-api-key"
      }
    }
  }
}
```

Restart Claude Desktop. The 5 Outrank tools are now available.

## Use case: autonomous SEO content loop

Typical agent flow:

1. Call `check_auth_and_credits()` to confirm the API key is valid and there are remaining credits for article generation
2. Call `list_products()` to see which managed websites you can target
3. Call `generate_keywords(product_id, topic)` to queue keyword research on a broad topic
4. Call `generate_article(product_id, keyword, auto_publish=false)` to generate a long-form SEO article (set `auto_publish=true` to push to the connected CMS automatically)
5. Call `get_article_content(article_id)` to fetch the finished markdown + HTML for review or further agent processing

The full content loop runs through these 5 tools without leaving the agent.

## Architecture

- Public MIT-licensed wrapper around the Outrank REST API v1
- Async HTTP via `httpx`
- pydantic v2 input validation
- Bearer token auth, server-side only
- Rate-limit aware (Outrank caps at 120 RPM and 10,000 RPD per key; the client reads `Retry-After` + `X-RateLimit-*` headers on 429 responses)

## Development

```bash
git clone https://github.com/NoBanks/outrank-mcp.git
cd outrank-mcp
pip install -e ".[dev]"
pytest
```

## License

MIT. See [LICENSE](LICENSE).

## Author

Ryan Hammer (NoBanks). Solo founder + engineer. Built this and 13 other MCP servers as part of a sprint to expose AI agent rails for the products and platforms shipping daily. Built outrank-mcp specifically as a same-day material reply to Tibo Maker's May 28 2026 newsletter asking which manual work people want AI agents to handle.

- GitHub: [@NoBanks](https://github.com/NoBanks)
- X/Twitter: [@livingagentic](https://x.com/livingagentic)
- Site: [livingagentic.me](https://livingagentic.me), [nohumannearby.com](https://nohumannearby.com)

Open to AI engineering roles, contract or full-time, remote-only.