rankrat

Search Console, Google Tag Manager, Bing Webmaster Tools, GA4, Microsoft Clarity, PageSpeed, Cloudflare, CrUX, and Bing's backlink data each have their own view of a site. Rankrat puts them behind one self-hosted service so a human can tell an agent what outcome they want and let the agent inspect, create, update, or remove supported provider resources.

It is a rat, not a burglar. You provide the provider accounts; those credentials are Rankrat's authority. Resource lists in boundaries.json are discovered inventory and URL-containment data, not a second permission system. Rankrat is writable by default. Set RANKRAT_READ_ONLY=true when a deployment must omit every mutating REST route and MCP tool.

Rankrat speaks MCP over stdio, MCP over Streamable HTTP at /mcp, and a FastAPI JSON API under /v1/. Wrapper-managed HTTP uses a bearer; a custom loopback-only launch may explicitly omit it.

Status: alpha. The API and tool surface may change before 1.0; minor releases can include documented incompatible changes, so pin an exact release if your integration requires stability.

Contents

• Capabilities

• Quick start

• Run it

• Safety model

• Documentation

• Agent integrations

• Development

• Project information

Related MCP server: gsc-mcp

Capabilities

Runtime discovery is authoritative: read-only deployments omit every write; writable deployments include onboarding with the other mutations. See the MCP tool catalog and generated OpenAPI document.

Quick start

Docker and GNU Make are the only checkout setup requirements. The guided setup prints the provider console URL and account-wide permissions for each selected provider, accepts credentials through hidden terminal prompts, stores them in standard owner-only paths, completes Google OAuth, and runs live capability checks before declaring the installation ready.

Rerunning setup is additive: selected providers are added or refreshed, while unselected accounts and their discovered inventory stay unchanged. If a provider already has multiple account entries, choose the intended entry in config/boundaries.json before refreshing that provider.

git clone https://github.com/psyb0t/rankrat.git
cd rankrat
make setup

make setup uses $HOME/.config/rankrat. Set RANKRAT_PROFILE=/absolute/path/to/rankrat-profile only when this checkout must use a different existing profile; installed users use the clearer rankrat --data-dir ... form instead.

Setup does not submit URLs or create site properties. It validates account access so a later agent session can do those jobs through the normal API/MCP tools. Exact provider details and the standalone-wrapper path are in Getting started and Providers and credentials.

Run it

make run             # MCP over stdio
make run-http        # Rankrat + Lighthouse over HTTP, attached to Compose
rankrat http -d      # same HTTP stack detached with automatic restarts

For HTTP, MCP is at http://127.0.0.1:8080/mcp; REST is under /v1/. Stdio uses no port or bearer. HTTP uses the selected data directory as its Compose project, creates docker-compose.yml there when missing, and preserves an existing operator file. The wrapper, plain docker run, Docker Compose, HTTP authentication, and client configurations are in Transports and deployment.

Compose runs two long-lived services plus one one-shot volume initializer; details are in the deployment guide.

Local browser audits use the separate psyb0t/rankrat-lighthouse image over a Unix socket; it receives no provider credentials. See Lighthouse.

Safety model

• Rankrat is writable by default. Configured account credentials authorize all supported provider operations and all resources those accounts can reach.

• RANKRAT_READ_ONLY=true removes write REST routes and MCP tools from runtime discovery. It is the only capability switch.

• The operator decides whether the caller is a careful human-directed agent or a fully autonomous one. Remote HTTP still uses the configured bearer.

• Resource arrays are cached inventory and containment data. Onboarding and discovery update them so retries reuse existing resources.

• Secrets are read-only mounts; OAuth records and monitor state have separate writable mounts.

See Configuration and Security before enabling writes or exposing HTTP beyond loopback.

Documentation

The documentation index links the complete operator and contributor manual: setup, configuration, providers, transports, workflows, security, tools, troubleshooting, and development.

The REST source is YAML-first: openapi.yaml, seo-openapi.yaml, and free-seo-openapi.yaml generate openapi.json. Agent clients can use the repository's skill, Claude Code and Codex manifests, or OpenClaw integration under .agents.

Agent integrations

The Rankrat skill works in agents that read .agents/skills/. The integrations below cover both MCP stdio and a shared Streamable HTTP server.

Claude Code

claude plugin marketplace add psyb0t/agents
claude plugin install rankrat@psyb0t

Codex

codex plugin marketplace add psyb0t/agents
codex plugin add rankrat@psyb0t

Installed through the catalog, the skill invokes as $rankrat:rankrat. Codex also discovers it as $rankrat directly from a Rankrat checkout.

OpenClaw

openclaw skills install @psyb0t/rankrat
openclaw plugins install clawhub:@psyb0t/rankrat

The plugin launches the published image over MCP stdio using the standard $HOME/.config/rankrat/ layout. Set one absolute RANKRAT_DATA_DIR in every client to reuse the same provider accounts, OAuth authorization, inventory, and monitor state from any site repository. To use an already-running shared server, configure OpenClaw for its authenticated http://127.0.0.1:8080/mcp Streamable HTTP endpoint. See Transports.

Development

All project tooling runs in containers:

make help
make lint
make test

Mocked tests need no provider credentials. Live tests are explicit and derive their sole account plus a safe target from the selected profile. See Development.

Project information

WTFPL license · Release history · Dependency attribution · Issues