Rankrat

rankrat

每项 SEO 指标都各自困在独立的封闭系统里，有自己的控制台、API，以及一套烦人的身份验证流程：Search Console 在这边，GA4 在那边，Bing Webmaster 在别处，此外还有 Cloudflare、Clarity、PageSpeed、CrUX、GTM，以及 Bing 的反向链接数据。让 Agent 查看你的排名，它就会淹没在八个控制台之间疲于奔命。Rankrat 把它们全都整合到一个可自托管的服务中，你只需告诉 Agent 想要什么结果，它就能通过一个统一入口检查、创建、更新或移除提供商资源——支持 REST 和 MCP，无需控制台。

它是只老鼠，不是窃贼。你提供各个服务商的账号；这些凭据就是它唯一的权限来源。boundaries.json 中的资源列表是清单和 URL 包含范围数据，并不是另设一套权限系统来假装保护你。Rankrat 默认可以写入；设置 RANKRAT_READ_ONLY=true 后，所有会修改数据的路由和工具都会从发现结果中消失。只需切换这一个开关。

它支持通过 stdio 使用 MCP、通过 /mcp 使用 MCP Streamable HTTP，并在 /v1/ 下提供 FastAPI JSON API。由封装程序管理的 HTTP 请求需要 bearer token；如果你知道自己在做什么，也可以手动启动仅限回环地址的服务并省略它。

状态： alpha。1.0 发布前，API 和工具接口仍可能变动——次要版本可能会有意引入不兼容变更（并提供说明），所以如果你需要稳定版本，请固定到一个精确版本。

目录

• 功能
• 快速开始
• 运行
• 安全模型
• 文档
• Agent 集成
• 开发
• 项目信息

功能

领域	Rankrat 提供的功能
Google	Search Console 分析、检查和站点地图；GA4 资源清单、历史报告和实时报告、电商、漏斗和受众；Google Tag Manager 容器、工作区、标签、触发器、变量、版本和发布；属性、站点地图、索引、所有权、入门配置和重命名操作
Bing	搜索、抓取、索引、站点地图、反向链接、配额、关键词、机会、关键词蚕食、网站／提交，以及安全的内容提交操作
性能	PageSpeed、Core Web Vitals、CrUX 历史数据、Microsoft Clarity 洞察、Cloudflare 分析，以及隔离的本地 Lighthouse 审计
网站智能	全站审计、结构化数据适用性、内部链接图、孤立页面、内容机会，以及跨服务商比较
所有权和入门配置	Google／Bing 检查、通过 Cloudflare 进行与服务商无关的 DNS 验证，以及幂等的 GA4／Search Console／Bing 入门配置
反向链接	为已配置网站提供 Bing Webmaster 反向链接情报
监控和修复	持久化监控和问题历史、站点地图／URL 重新提交、IndexNow、精确的 Cloudflare 清除操作、有限的缓存模板，以及托管式边缘重定向

运行时公布的功能就是它实际提供的功能——没有隐藏端点。只读部署会从发现结果中移除所有写入操作；可写部署则会像其他功能一样公开入门配置。完整列表见 MCP 工具目录和生成的 OpenAPI 文档。

快速开始

安装 rankrat 命令，为需要使用的服务商创建凭据，然后运行它。Docker 是唯一的运行时依赖。

安装

下载安装程序，阅读后运行——可选择按用户安装（无需 root）或 全系统安装：

curl -fsSL https://raw.githubusercontent.com/psyb0t/rankrat/main/install.sh -o rankrat-install.sh
less rankrat-install.sh
bash rankrat-install.sh                # per-user   -> ~/.local/bin/rankrat
sudo bash rankrat-install.sh --system  # system-wide -> /usr/local/bin/rankrat

安装模式会根据运行者自动检测；--user / --system 可强制指定模式， --uninstall 则会移除命令。这会将 rankrat 包装脚本添加到 PATH 中—— 这是一个可读脚本，用于驱动已发布的 Docker 镜像。更愿意从源码检出版本 开始？克隆仓库并使用 ./rankrat 或 make 目标；请参阅开始使用。

设置

运行设置程序。它会列出所有提供商，你可以选择实际使用的提供商；随后引导 你创建各项凭据——包括 Google OAuth、Bing Webmaster 密钥、Cloudflare 令牌、 Clarity 令牌的具体控制台操作——然后隐藏你粘贴的所有值。无需从 README 中复制令牌权限：

rankrat setup

配置 Google？设置程序提示时，在隐藏输入框中粘贴单行 Desktop OAuth 客户端 JSON，与其他凭据的操作相同。

设置程序会验证账户访问权限——不会提交 URL 或创建资源。你的配置文件位于 ~/.config/rankrat；启动时可使用 rankrat --data-dir /absolute/path 或 RANKRAT_DATA_DIR 覆盖，为每个账户或工作区使用单独的配置文件。想提前了解 凭据设置步骤，或各提供商实际提供的内容？请参阅 提供商和凭据。从源码检出版本开始时，设置步骤为 make setup。

运行

rankrat            # MCP over stdio (default)
rankrat http -d    # REST + Streamable-HTTP MCP + Lighthouse, detached with restarts
rankrat upgrade    # re-pin to the latest release, pull it, drop the previous image

从源码检出版本开始：make run（stdio）和 make run-http（通过 Compose 运行 HTTP，并以前台方式附加）。

rankrat setup 会将 psyb0t/rankrat 和 psyb0t/rankrat-lighthouse 都固定到 最新发布标签——记录在配置文件根目录的 .env 中，同时记录 HTTP 端口和只读 标志——而不是跟踪不断变化的 :latest。rankrat upgrade 会将镜像重新固定到 最新发布版本，拉取两个镜像，重启正在运行的 HTTP 服务栈（沿用记录的端口和 只读标志），并移除已被替换的镜像；端口和只读配置行保持不变。传入 --rolling（或设置 RANKRAT_ROLLING=1）可在单次运行中使用不断变化的 :latest 镜像，而不更改已记录的固定版本。每次运行仍可通过 RANKRAT_IMAGE、 RANKRAT_LIGHTHOUSE_IMAGE、RANKRAT_HTTP_PORT 和 RANKRAT_READ_ONLY 覆盖记录的值。

若要一次性设置主机配置，而非每次运行时设置，请将其放入位于 ~/.config/rankrat/.env 的永久主机环境文件中（使用 RANKRAT_ENV_FILE 覆盖路径）。包装脚本会在选择配置文件前读取该文件，因此可以设置 RANKRAT_DATA_DIR（要使用的配置文件），以及 RANKRAT_READ_ONLY、 RANKRAT_IMAGE、RANKRAT_LIGHTHOUSE_IMAGE、RANKRAT_HTTP_PORT、 RANKRAT_OAUTH_CALLBACK_PORT 和 RANKRAT_ROLLING。它只会填充未设置或为空的 变量，因此 --data-dir 标志或实际环境变量仍可覆盖它。这对使用精简环境运行 rankrat、无法读取你的 shell 导出变量的 MCP 启动器尤其方便。此文件与每个配置 文件的 .env 相互独立：主机文件用于选择配置文件和主机默认值，而配置文件的 .env 用于固定该配置文件的镜像、端口和只读标志。

通过 HTTP 使用时，MCP 位于 http://127.0.0.1:8080/mcp，REST 位于 /v1/ 下； stdio 无需端口，也无需 bearer。HTTP 会将你的数据目录作为 Compose 项目——如果 目录中没有 docker-compose.yml，就会创建一个；如果已有文件，则绝不会修改。 底层由两个长期运行的服务和一个一次性卷初始化器组成。包装脚本、直接使用 docker run、原始 Compose、HTTP 身份验证和客户端接入方式都详见 传输方式和部署。

浏览器审计会在单独的 psyb0t/rankrat-lighthouse 镜像中通过 Unix 套接字运行， 并且绝不会接触任何提供商凭据。rankrat stdio 会为会话启动一个临时的 Lighthouse sidecar——能力与 HTTP 相同——并在退出时将其关闭；包装脚本会在主机端启动它， 因此应用无需接触 Docker 套接字，只通过该套接字访问 Lighthouse。请参阅 Lighthouse。

安全模型

• Rankrat 默认可写。已配置的账户凭据允许执行所有受支持的提供商操作，以及访问这些账户可访问的所有资源。
• RANKRAT_READ_ONLY=true 会从运行时发现中移除写入 REST 路由和 MCP 工具。这是唯一的能力开关。
• 由操作员决定调用方是谨慎、由人类指导的 Agent，还是完全自主的 Agent。远程 HTTP 仍使用已配置的 bearer。
• 资源数组是缓存的清单和范围控制数据。引导和发现过程会更新这些数据，使重试可以复用现有资源。
• 密钥以只读挂载方式提供；OAuth 记录和监控状态则使用独立的可写挂载。

在启用写入或将 HTTP 暴露到本地回环地址以外之前，请参阅配置和安全。

文档

• 快速入门 — 安装、文件位置、验证设置
• 配置 — 所有边界字段和运行时开关
• 提供商和凭据 — 获取各项凭据及其权限
• 传输方式和部署 — stdio MCP、Streamable HTTP MCP、REST、Compose、Agent 集成
• 功能工作流 — 常见 SEO、分析、反向链接和索引问题的操作
• Lighthouse — 浏览器工作进程及其安全限制
• 所有权和引导 — Google/Bing 资源创建和 DNS 验证
• 监控和修复 — 持久化监控和提供商写入行为
• 安全 — 信任边界和生产环境规则
• MCP 工具参考 — 所有可发现的 MCP 工具
• 故障排除 — 启动、OAuth、提供商、站点地图和浏览器审计故障
• 开发 — 构建、测试、生成契约、审计依赖项、贡献

REST 源文件以 YAML 为准：openapi.yaml、 seo-openapi.yaml 和 free-seo-openapi.yaml 会生成 openapi.json。Agent 客户端可以使用此代码库的 skill、 Claude Code 和 Codex 清单，或 .agents 中的 OpenClaw 集成。

Agent 集成

Rankrat skill 适用于能够读取 .agents/skills/ 的 Agent（例如 peen）。以下集成涵盖 MCP stdio 和共享的 Streamable HTTP 服务。

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

通过目录安装后，该 skill 会以 $rankrat:rankrat 的形式调用。Codex 也可以直接从 Rankrat 检出目录中将其识别为 $rankrat。

OpenClaw

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

该插件通过 MCP stdio 启动已发布的镜像，并使用标准的 $HOME/.config/rankrat/ 布局。在每个客户端中设置同一个绝对路径 RANKRAT_DATA_DIR，即可从任何站点代码库复用相同的提供商账户、OAuth 授权、清单 和监控状态。若要使用已运行的共享服务，请将 OpenClaw 配置为使用经过身份验证的 http://127.0.0.1:8080/mcp Streamable HTTP 端点。请参阅传输方式。

开发

所有操作都在容器中运行——不必再赌“在我的机器上能运行”：

make help
make lint
make test

模拟测试无需任何凭据。实时测试为可选项，会直接从你的配置文件中读取一个账户和一个安全目标，因此不会误入其他地方，也不会触碰不该触碰的内容。完整的贡献者指南请参阅 开发。

项目信息

WTFPL 许可证 · 发布历史 · 依赖项 归属说明 · 问题