{
  "markdown": "# rankrat\n\n<!-- mcp-name: io.github.psyb0t/rankrat -->\n\n[![CI](https://github.com/psyb0t/rankrat/actions/workflows/pipeline.yml/badge.svg?branch=main)](https://github.com/psyb0t/rankrat/actions/workflows/pipeline.yml)\n[![coverage](https://raw.githubusercontent.com/psyb0t/rankrat/badges/coverage.svg)](https://github.com/psyb0t/rankrat/actions/workflows/pipeline.yml)\n[![version](https://raw.githubusercontent.com/psyb0t/rankrat/badges/version.svg)](https://github.com/psyb0t/rankrat/releases)\n[![license](https://raw.githubusercontent.com/psyb0t/rankrat/badges/license.svg)](LICENSE)\n[![Docker Pulls](https://img.shields.io/docker/pulls/psyb0t/rankrat?style=flat-square)](https://hub.docker.com/r/psyb0t/rankrat)\n\nEvery SEO signal lives in its own walled garden with its own dashboard, its own\nAPI, and its own bullshit auth dance: Search Console over here, GA4 over there,\nBing Webmaster somewhere else, plus Cloudflare, Clarity, PageSpeed, CrUX, GTM,\nand Bing's backlink data. Point an agent at your rankings and it drowns juggling\neight consoles. Rankrat drags all of them behind one self-hosted service, so you\ntell an agent the outcome you want and it inspects, creates, updates, or rips\nout provider resources through a single surface — REST and MCP, no dashboards.\n\nIt's a rat, not a burglar. You hand it the provider accounts; those credentials\nare the only authority it has. The resource lists in `boundaries.json` are\ninventory and URL-containment data — not a second permission system pretending\nto keep you safe. Rankrat writes by default; set `RANKRAT_READ_ONLY=true` and\nevery mutating route and tool disappears from discovery. That's the one switch.\n\nIt speaks MCP over stdio, MCP over Streamable HTTP at `/mcp`, and a FastAPI JSON\nAPI under `/v1/`. Wrapper-managed HTTP gets a bearer; a hand-rolled loopback-only\nlaunch can drop it if you know what you're doing.\n\n**Status:** alpha. The API and tool surface can still move before 1.0 — minor\nreleases may break things on purpose (documented), so pin an exact release if\nyou need it to hold still.\n\n## Contents\n\n- [Capabilities](#capabilities)\n- [Quick start](#quick-start)\n- [Run it](#run-it)\n- [Safety model](#safety-model)\n- [Documentation](#documentation)\n- [Agent integrations](#agent-integrations)\n- [Development](#development)\n- [Project information](#project-information)\n\n## Capabilities\n\n| Area | What Rankrat exposes |\n| --- | --- |\n| Google | Search Console analytics, inspection and sitemaps; GA4 inventory, historical and realtime reports, ecommerce, funnels, and audiences; Google Tag Manager containers, workspaces, tags, triggers, variables, versions, and publication; property, sitemap, indexing, ownership, onboarding, and rename writes |\n| Bing | Search, crawl, indexing, sitemap, backlink, quota, keyword, opportunity, cannibalization, site/submission, and safe content-submission operations |\n| Performance | PageSpeed, Core Web Vitals, CrUX history, Microsoft Clarity insights, Cloudflare analytics, and isolated local Lighthouse audits |\n| Site intelligence | Whole-site audits, schema eligibility, internal-link graphs, orphan pages, content opportunities, and cross-provider comparisons |\n| Ownership and onboarding | Google/Bing checks, provider-neutral DNS verification through Cloudflare, and idempotent GA4/Search Console/Bing onboarding |\n| Backlinks | Bing Webmaster backlink intelligence for configured sites |\n| Monitoring and remediation | Persistent monitors and issue history, sitemap/URL resubmission, IndexNow, exact Cloudflare purges, finite cache templates, and managed edge redirects |\n\nWhat the runtime advertises is what it does — no hidden endpoints. A read-only\ndeployment drops every write from discovery; a writable one exposes onboarding\nalongside the rest. The whole list is the [MCP tool catalog](docs/tool-reference.md)\nand the generated [OpenAPI document](openapi.json).\n\n## Quick start\n\nInstall the `rankrat` command, create the credentials for the providers you\nwant, then run it. Docker is the only runtime requirement.\n\n### Install\n\nDownload the installer, read it, then run it — per-user (no root) or\nsystem-wide:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/psyb0t/rankrat/main/install.sh -o rankrat-install.sh\nless rankrat-install.sh\nbash rankrat-install.sh                # per-user   -> ~/.local/bin/rankrat\nsudo bash rankrat-install.sh --system  # system-wide -> /usr/local/bin/rankrat\n```\n\nThe mode auto-detects from who runs it; `--user` / `--system` force it and\n`--uninstall` removes the command. This puts the `rankrat` wrapper — a readable\nscript that drives the published Docker images — on your PATH. Prefer to work\nfrom a source checkout? Clone the repo and use `./rankrat` or the `make` targets\ninstead; see [Getting started](docs/getting-started.md).\n\n### Set up\n\nRun setup. It lists every provider, you pick the ones you actually use, and it\nwalks you through creating each credential — the exact console clicks for Google\nOAuth, the Bing Webmaster key, the Cloudflare token, the Clarity token — then\nhides every value you paste. No copying token permissions out of a README:\n\n```sh\nrankrat setup\n```\n\nConfiguring Google? Paste the one-line Desktop OAuth client JSON at the hidden\nprompt when setup asks — same as every other credential.\n\nSetup validates account access — it does not submit URLs or create properties.\nYour profile lives in `~/.config/rankrat`; override it per launch with\n`rankrat --data-dir /absolute/path` or `RANKRAT_DATA_DIR` for a separate profile\nper account or workspace. Want to read the credential steps ahead of time, or\nwhat each provider actually gives you? See\n[Providers and credentials](docs/providers.md). From a source checkout the setup\nstep is `make setup`.\n\n## Run it\n\n```sh\nrankrat            # MCP over stdio (default)\nrankrat http -d    # REST + Streamable-HTTP MCP + Lighthouse, detached with restarts\nrankrat upgrade    # re-pin to the latest release, pull it, drop the previous image\n```\n\nFrom a source checkout: `make run` (stdio) and `make run-http` (HTTP over\nCompose, attached).\n\n`rankrat setup` pins both `psyb0t/rankrat` and `psyb0t/rankrat-lighthouse` to the\nlatest release tag — recorded, along with the HTTP port and read-only flag, in a\n`.env` at your profile root — rather than tracking the moving `:latest`. `rankrat\nupgrade` re-pins the images to the newest release, pulls both, restarts a running\nHTTP stack (reusing the recorded port and read-only flag), and removes the\nsuperseded images; it leaves the port and read-only lines untouched. Pass\n`--rolling` (or set `RANKRAT_ROLLING=1`) to use the moving `:latest` images for a\nsingle run without touching the recorded pin. `RANKRAT_IMAGE`,\n`RANKRAT_LIGHTHOUSE_IMAGE`, `RANKRAT_HTTP_PORT`, and `RANKRAT_READ_ONLY` still\noverride the recorded values per run.\n\nTo set the host settings once instead of per run, put them in a permanent host\nenv file at `~/.config/rankrat/.env` (override the path with `RANKRAT_ENV_FILE`).\nThe wrapper reads it before selecting a profile, so it can set `RANKRAT_DATA_DIR`\n(which profile to use) along with `RANKRAT_READ_ONLY`, `RANKRAT_IMAGE`,\n`RANKRAT_LIGHTHOUSE_IMAGE`, `RANKRAT_HTTP_PORT`, `RANKRAT_OAUTH_CALLBACK_PORT`,\nand `RANKRAT_ROLLING`. It only fills a variable that is unset or empty, so a\n`--data-dir` flag or a real env var still overrides it. This is especially handy\nfor MCP launchers that run `rankrat` with a minimal environment and never see\nyour shell exports. It is separate from the per-profile `.env`: the host file\nselects the profile and the host defaults, while a profile's `.env` pins that\nprofile's images, port, and read-only flag.\n\nOver HTTP, MCP lives at `http://127.0.0.1:8080/mcp` and REST under `/v1/`; stdio\nneeds no port and no bearer. HTTP treats your data directory as its Compose\nproject — it drops a `docker-compose.yml` in there if one's missing and never\ntouches yours if it isn't. Under the hood that's two\nlong-lived services plus one one-shot volume initializer. The wrapper, plain\n`docker run`, raw Compose, HTTP auth, and client wiring all live in\n[Transports and deployment](docs/transports.md).\n\nBrowser audits run in a separate `psyb0t/rankrat-lighthouse` image over a Unix\nsocket, and it never sees a single provider credential. `rankrat` stdio brings up\nan ephemeral Lighthouse sidecar for the session — same capability as HTTP — and\ntears it down on exit; the wrapper launches it host-side, so the app stays off the\nDocker socket and reaches Lighthouse only over the socket. See [Lighthouse](docs/lighthouse.md).\n\n## Safety model\n\n- Rankrat is writable by default. Configured account credentials authorize all\n  supported provider operations and all resources those accounts can reach.\n- `RANKRAT_READ_ONLY=true` removes write REST routes and MCP tools from runtime\n  discovery. It is the only capability switch.\n- The operator decides whether the caller is a careful human-directed agent or\n  a fully autonomous one. Remote HTTP still uses the configured bearer.\n- Resource arrays are cached inventory and containment data. Onboarding and\n  discovery update them so retries reuse existing resources.\n- Secrets are read-only mounts; OAuth records and monitor state have separate\n  writable mounts.\n\nSee [Configuration](docs/configuration.md) and [Security](docs/security.md)\nbefore enabling writes or exposing HTTP beyond loopback.\n\n## Documentation\n\n- [Getting started](docs/getting-started.md) — install, file locations, verifying setup\n- [Configuration](docs/configuration.md) — every boundary field and runtime switch\n- [Providers and credentials](docs/providers.md) — obtaining each credential and its permissions\n- [Transports and deployment](docs/transports.md) — stdio MCP, Streamable HTTP MCP, REST, Compose, agent integrations\n- [Feature workflows](docs/features.md) — operations for common SEO, analytics, backlink, and indexing questions\n- [Lighthouse](docs/lighthouse.md) — the browser worker and its security limits\n- [Ownership and onboarding](docs/ownership-and-onboarding.md) — Google/Bing property creation and DNS verification\n- [Monitoring and remediation](docs/monitoring-and-remediation.md) — persistent monitors and provider-write behavior\n- [Security](docs/security.md) — trust boundaries and production rules\n- [MCP tool reference](docs/tool-reference.md) — every discoverable MCP tool\n- [Troubleshooting](docs/troubleshooting.md) — startup, OAuth, provider, sitemap, and browser-audit failures\n- [Development](docs/development.md) — build, test, generate contracts, audit dependencies, contribute\n\nThe REST source is YAML-first: [`openapi.yaml`](src/rankrat/api/openapi.yaml),\n[`seo-openapi.yaml`](src/rankrat/api/seo-openapi.yaml), and\n[`free-seo-openapi.yaml`](src/rankrat/api/free-seo-openapi.yaml) generate\n[`openapi.json`](openapi.json). Agent clients can use the repository's skill,\nClaude Code and Codex manifests, or OpenClaw integration under [`.agents`](.agents/).\n\n## Agent integrations\n\nThe [Rankrat skill](.agents/skills/rankrat) works in agents that read\n`.agents/skills/`. The integrations below cover both MCP stdio and a shared\nStreamable HTTP server.\n\n### Claude Code\n\n```sh\nclaude plugin marketplace add psyb0t/agents\nclaude plugin install rankrat@psyb0t\n```\n\n### Codex\n\n```sh\ncodex plugin marketplace add psyb0t/agents\ncodex plugin add rankrat@psyb0t\n```\n\nInstalled through the catalog, the skill invokes as `$rankrat:rankrat`. Codex\nalso discovers it as `$rankrat` directly from a Rankrat checkout.\n\n### OpenClaw\n\n```sh\nopenclaw skills install @psyb0t/rankrat\nopenclaw plugins install clawhub:@psyb0t/rankrat\n```\n\nThe plugin launches the published image over MCP stdio using the standard\n`$HOME/.config/rankrat/` layout. Set one absolute `RANKRAT_DATA_DIR` in every\nclient to reuse the same provider accounts, OAuth authorization, inventory,\nand monitor state from any site repository. To use an already-running shared server,\nconfigure OpenClaw for its authenticated `http://127.0.0.1:8080/mcp`\nStreamable HTTP endpoint. See [Transports](docs/transports.md#agent-integrations).\n\n## Development\n\nEverything runs in containers — no \"works on my machine\" roulette:\n\n```sh\nmake help\nmake lint\nmake test\n```\n\nMocked tests need zero credentials. Live tests are opt-in and pull their one\naccount plus a safe target straight from your profile, so they can't wander off\nand touch something they shouldn't. Full contributor guide in\n[Development](docs/development.md).\n\n## Project information\n\n[WTFPL license](LICENSE) · [Release history](CHANGELOG.md) · [Dependency\nattribution](THIRD_PARTY_LICENSES.md) · [Issues](https://github.com/psyb0t/rankrat/issues)\n",
  "bytes": 12633,
  "sha": "c445ee12be37f126d9d47e13697b591d1059ca2f69c4de54f55e91c8617d337d",
  "repo_slug": "psyb0t/rankrat",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_psyb0t_rankrat_ccf137fa/readme"
}