searchdock-cli

SearchDock CLI — Google Search Console 命令行工具

在终端或 AI Agent 中读取 Google Search Console 分析数据、检查已编入索引的网址并监控站点地图。

SearchDock 是开源的，可在本地运行，并且只请求 Google 只读权限。你可以通过 npm、Python、MCP、Codex 或 Claude Code 插件，或独立的 Agent 技能使用相同的核心功能。计划支持 Bing Webmaster Tools。

与 Agent 一起设置

将此提示词复制到你的编码 Agent 中：

Set up SearchDock CLI for this project using
https://github.com/xplormityai/searchdock-cli. Read its README and
skills/searchdock-setup/SKILL.md. Check Node.js 22+, reuse an existing
installation, or install the CLI from npm. Install searchdock-setup and
searchdock skills for the agent I am using, scoped to this project, and
connect the stdio MCP server if this agent supports it. Keep existing
agent configuration. For Google access, ask only for the local path to
my Desktop OAuth client JSON and guide me through read-only browser
consent. Never print credentials or tokens. Let me choose the Search
Console property, then verify the connection with a metrics request.
Tell me exactly which steps succeeded and what still needs my input.

安装命令

所有发行版本均要求 Node.js 22 或更高版本。

软件包：npm · PyPI。

# npm
npm install --global searchdock-cli
searchdock --help

# No global installation
npx --yes [email protected] --help

# Python; Node.js is still required
pipx install searchdock-cli
# Alternatively: python -m pip install searchdock-cli

Python 软件包是一个启动器，包含完全相同的 JavaScript 运行时。它没有单独的 Google 实现。如果两个软件包都已安装，请使用 python -m searchdock_cli 明确选择 Python 启动器。

在当前项目中为 Codex 安装这两项技能：

npx --yes skills add xplormityai/searchdock-cli --skill searchdock-setup searchdock --agent codex --copy --yes

将 codex 替换为 claude-code、cursor、opencode 或你的受支持的 Agent。仅在要跨项目安装时添加 --global。技能不会安装 CLI，也不会授权 Google 访问权限。插件、MCP 和手动设置。

从源代码运行：

git clone https://github.com/xplormityai/searchdock-cli.git
cd searchdock-cli
npm ci
npm run build
node dist/cli.cjs --help

连接 Google Search Console

在你自己的 Google Cloud 项目中创建一个 Google OAuth 桌面应用客户端，启用 Search Console API，并下载客户端 JSON。具体步骤和测试模式限制请参阅 Google 设置。本项目不包含共享的开发者凭据。

searchdock auth login --client-file /path/to/desktop-client.json
searchdock sites list
searchdock sites use sc-domain:example.com
searchdock auth status

Google 会打开本地浏览器授权流程。SearchDock 使用 PKCE、验证回调状态，并且只监听 127.0.0.1。它请求 webmasters.readonly 权限，并将刷新令牌保存在操作系统的每用户配置目录中，位于此代码库之外。凭据以受权限保护的本地 JSON 文件形式存储，SearchDock 不会对其加密。请参阅隐私说明。

命令

# Search performance and top queries
searchdock analytics --days 28
searchdock analytics --dimensions page --days 28 --json
searchdock analytics --dimensions date --start 2026-09-01 --end 2026-09-30

# Exact, case-insensitive brand queries
searchdock analytics --brand "Your Brand" --json

# Sitemaps and Google's indexed URL status
searchdock sitemaps
searchdock inspect https://example.com/

# Combined report, including only the URLs you specify
searchdock report --urls https://example.com/,https://example.com/about --json
searchdock report --output ./private-report.json

# Multiple accounts/sites
searchdock auth login --client-file /path/to/client.json --profile work
searchdock sites use https://example.com/ --profile work
searchdock analytics --profile work --site https://example.com/ --json

# Diagnostics and local credential removal
searchdock doctor
searchdock auth logout

--json 会将机器可读的结果写入标准输出，并将错误写入标准错误；发生错误时返回非零退出状态。--output 会将 JSON 保存到一个新文件中，并拒绝覆盖已有文件。请自行确保私有报告不被提交到 Git。目前尚不支持 CSV。对于包含逗号的网址，请使用 MCP urls 数组或 JavaScript API 进行批量检查。

报告窗口默认采用太平洋时间，从今天前三天起往前追溯 28 天，以便 Search Console 有时间处理数据。你也可以指定确切日期。最终数据仍可能延迟。分页最多支持请求 100,000 行，但 Google 的 API 只会返回排名靠前的行，并会省略部分匿名查询数据。缺少数据行并不能证明需求为零；展示次数为零时，平均排名没有意义。

AI Agent 和 MCP

SearchDock 提供五个只读 MCP 工具：searchdock_sites、searchdock_analytics、searchdock_sitemaps、searchdock_inspect 和 searchdock_report。请先在本地完成身份验证；MCP 工具不会启动授权流程，也不会更改账户设置。

将此 stdio 服务添加到任何兼容的 MCP 客户端：

{
  "mcpServers": {
    "searchdock": {
      "command": "npx",
      "args": ["--yes", "[email protected]", "mcp"]
    }
  }
}

对于源代码检出，将 command 设为 node，并将 args 设为 ["/absolute/path/searchdock-cli/dist/cli.cjs", "mcp"]。通过 shell 启动 npx.cmd 的 Windows 客户端可能需要将 command 设为 "cmd"，并将 args 设为 ["/c", "npx", "--yes", "[email protected]", "mcp"]。请参阅客户端的 Windows 配置指南。

插件使用相同的固定 npm 版本：

# Codex CLI
codex plugin marketplace add xplormityai/searchdock-cli
codex plugin add searchdock@searchdock

在 Claude Code 中：

/plugin install searchdock --marketplace xplormityai/searchdock-cli --scope project

此一步式命令要求 Claude Code 2.1.275+。较早版本可以使用 /plugin marketplace add xplormityai/searchdock-cli，然后运行 /plugin install searchdock@searchdock --scope project。

若要单独安装技能，请将 skills/searchdock 和 skills/searchdock-setup 都复制到 Agent 的技能目录中。Codex 使用 ~/.agents/skills/；Claude Code 使用 ~/.claude/skills/。请单独安装 CLI。插件中包含这两项技能。此仓库包含可移植的 Agent Plugins、Codex 和 Claude 清单；本地 stdio 插件不会自动列入托管插件目录。

你也可以通过开放技能安装器安装技能：

npx --yes skills add xplormityai/searchdock-cli --skill searchdock-setup searchdock --agent codex --copy --yes

SearchDock 已发布到官方 MCP 注册表，条目为 io.github.xplormityai/searchdock-cli。发布工作流使用 GitHub OIDC 更新其元数据。

SearchDock 和 setup 技能均已发布到 ClawHub。根据该注册表的要求，其技能副本采用 MIT-0 许可；此仓库及其软件包仍采用 MIT 许可。

本地 MCPB 捆绑包已发布到 Smithery。它需要 Node.js 22+ 和已在本地完成身份验证的 Google 个人资料；其中不包含凭据。python scripts/build_mcpb.py 会打包已构建的 dist/cli.cjs。发布和发现自动化。

Google API 能告诉你什么，不能告诉你什么

可用	需要使用 Search Console 界面或导出
点击次数、展示次数、点击率、平均排名	请求编入索引
热门查询/网页以及按日期/设备/国家/地区划分的数据	测试在线网址
精确的品牌查询表现	完整的网页索引排除项表
站点地图处理状态	手动操作和安全问题
Google 已编入索引的特定网址版本	保证当前排名或索引状态

SearchDock 的报告会标记返回的站点地图错误/警告、待处理状态，以及你检查的网址中不为 PASS 的判定。它并非完整的技术 SEO 审核，也不会捏造 SEO/AEO/GEO 评分。

JavaScript API

import { selectedContext } from 'searchdock-cli';

const { adapter, site } = await selectedContext({ profile: 'default' });
const result = await adapter.analytics(site, { days: 28, dimensions: ['page'] });
console.log(result.rows);

提供方注册表会单独声明功能。无需更改 CLI、MCP 或 Python 分发模式，即可将 Bing 添加为适配器。必须明确说明各提供方的差异。请参阅架构。

开发和发布

npm ci
npm run build
npm test
npm run check
python -m pip install build twine
npm run release:artifacts
python -m twine check dist/releases/searchdock_cli-0.1.3-py3-none-any.whl dist/releases/searchdock_cli-0.1.3.tar.gz

发布说明介绍 npm/PyPI 账户、OIDC 可信发布、版本控制和 GitHub 发布构件。仅创建软件包并不会发布任何内容。

由 Xplormity Collective 构建。MIT 许可证。