cws

cws-mcp

한국어

用于管理 Chrome Web Store 扩展程序的 MCP 服务。可直接通过 Claude Code 或任何 MCP 客户端上传、发布和管理 Chrome 扩展程序。

适用场景

在以下情况下使用此 MCP：

• “上传我的 Chrome 扩展程序的新版本” — 构建 ZIP 文件，并使用 upload 工具将其作为草稿上传
• “将我的扩展程序发布到 Chrome Web Store” — 使用 publish 提交审核并正式发布
• “查看我的扩展程序的审核状态” — 使用 status 查看审核状态、版本和发布百分比
• “更新我的扩展程序的说明或类别” — 使用 update-metadata 保存并验证草稿商品信息
• “取消待处理的提交” — 使用 cancel 撤回正在审核的提交
• “为我的扩展程序设置分阶段发布” — 使用分阶段发布选项调用 publish，然后使用 deploy-percentage 逐步提高发布比例

工具

工具	说明
upload	将 ZIP 文件上传到 Chrome Web Store（更新现有商品草稿）
publish	使用发布类型、发布百分比、跳过审核和 blockOnWarnings 提交／发布
status	获取当前状态，包括审核状态、发布百分比和版本
cancel	取消待处理的提交
deploy-percentage	设置分阶段发布百分比（0-100，必须高于当前目标值）
get	status 的别名：获取 v2 发布状态，而非商品信息文本
get-metadata-ui	从控制面板读取当前草稿说明、类别、主页 URL 和支持 URL
update-metadata	通过控制面板保存上述四个受支持的草稿字段，并在重新加载后验证
update-metadata-ui	update-metadata 的别名

API 覆盖范围

如果上传返回 IN_PROGRESS，则表示上传仍在进行中：请轮询 status，直到 lastAsyncUploadState 为 SUCCEEDED 后再发布。FAILED 表示工具错误。发布受阻时会保留 error.details，其中包含需要处理的警告。

此 MCP 服务涵盖 Chrome Web Store API v2 的所有端点：

v2 端点	MCP 工具
media.upload	upload
publishers.items.publish	publish
publishers.items.fetchStatus	status
publishers.items.cancelSubmission	cancel
publishers.items.setPublishedDeployPercentage	deploy-percentage

所有 API 请求均使用 v2。公开 API 没有读取／写入商品信息文本的端点；控制面板工具使用 Playwright 和单独登录的 Chrome 配置文件。保存商品信息字段不会提交审核。字段缺失、类别不匹配或保存未确认时会返回错误，而非成功。

设置

需要 Node.js 20 或更高版本，以符合 Playwright 的运行时要求。

1. 创建 OAuth2 凭据

1. 前往 Google Cloud Console
2. 创建项目（或选择现有项目）
3. 启用 Chrome Web Store API
4. 创建 OAuth2 凭据（桌面应用类型）
5. 记下你的 Client ID 和 Client Secret

2. 获取刷新令牌

按照 Google 的桌面应用 OAuth 流程操作，使用本地回环重定向 URI、PKCE 和作用域 https://www.googleapis.com/auth/chromewebstore。请求离线访问（access_type=offline；需要新的刷新令牌时使用 prompt=consent）。使用相同的重定向 URI 交换授权码，并将刷新令牌保存在 MCP 客户端的密钥／环境设置中。Google 已不再支持此前的复制粘贴式 OOB 重定向。

3. 配置 MCP

将以下内容添加到 Claude Code MCP 设置（~/.claude/settings.local.json）：

{
  "mcpServers": {
    "cws-mcp": {
      "command": "node",
      "args": ["/path/to/cws-mcp/dist/index.js"],
      "env": {
        "CWS_CLIENT_ID": "xxxxx.apps.googleusercontent.com",
        "CWS_CLIENT_SECRET": "GOCSPX-xxxxx",
        "CWS_REFRESH_TOKEN": "1//xxxxx",
        "CWS_PUBLISHER_ID": "me",
        "CWS_ITEM_ID": "your-extension-id"
      }
    }
  }
}

或者通过 npm 全局安装：

{
  "mcpServers": {
    "cws-mcp": {
      "command": "npx",
      "args": ["-y", "cws-mcp"],
      "env": { ... }
    }
  }
}

环境变量

变量	必填	描述
CWS_CLIENT_ID	是	Google OAuth2 客户端 ID
CWS_CLIENT_SECRET	是	Google OAuth2 客户端密钥
CWS_REFRESH_TOKEN	是	OAuth2 刷新令牌
CWS_PUBLISHER_ID	否	发布者 ID（默认值：me）
CWS_ITEM_ID	否	默认扩展程序条目 ID
CWS_DASHBOARD_PROFILE_DIR	否	用于 UI 自动化的浏览器配置文件路径（默认值：~/.cws-mcp-profile）

使用示例

检查扩展程序状态

Use the cws-mcp status tool

上传并发布

1. Use cws-mcp upload with zipPath="/path/to/extension.zip"
2. Use cws-mcp publish

等待批准后再发布

Use cws-mcp publish with:
- publishType="STAGED_PUBLISH"

使用 skip-review 发布

Use cws-mcp publish with skipReview=true

STAGED_PUBLISH 会暂存已批准的提交，以便稍后发布；它不是发布比例。对于符合条件的扩展程序，请单独使用 deployPercentage 进行渐进式发布。

验证出现警告时停止发布

Use cws-mcp publish with blockOnWarnings=true

默认值为 false，与 API 一致。即使发布成功，也请检查返回的 warningInfo.warnings。

读取或保存商店详情字段，但不提交审核

Use cws-mcp get-metadata-ui with headless=false
Use cws-mcp update-metadata with:
- description="..."
- category="Developer Tools"
- homepageUrl="https://example.com"
- supportUrl="https://example.com/support"

注意：

• category 必须与当前控制面板语言中显示的选项标签完全一致；支持英文和韩文的字段标签。
• 这些工具会读取／保存当前控制面板草稿，而非已发布的商店详情或任意区域设置。请先在控制面板中选择目标本地化版本；遇到有歧义的字段时，操作会安全失败。
• 如需更改标题、摘要和默认语言区域，请修改 manifest.json／本地化消息，重新构建，然后上传 ZIP。图标和屏幕截图请直接在控制面板中处理。
• 如果需要登录，请先使用 headless=false 运行。
• 浏览器配置文件路径默认为 ~/.cws-mcp-profile（可使用 CWS_DASHBOARD_PROFILE_DIR 覆盖）。
• 必须安装 Google Chrome。控制面板 UI 的更改可能需要更新选择器；未验证的保存操作会返回错误。对于结果不明确的失败，请先检查控制面板，再重试。

渐进式发布

1. Use cws-mcp publish with deployPercentage=10
2. Monitor approval/publication with status
3. Use cws-mcp deploy-percentage with percentage=50
4. Use cws-mcp deploy-percentage with percentage=100

注意：deploy-percentage 仅适用于过去 7 天活跃用户数达到 10,000+ 的扩展程序。新的百分比必须始终高于当前目标值。

从 1.x 迁移到 2.0

Google 将于 2026 年 10 月 15 日关闭 API v1。2.0 版本不再调用该 API：

• get 现在返回 v2 状态。旧版 projection 参数已被拒绝；如需读取草稿中的商店详情文本，请使用 get-metadata-ui。v2 不会公开已发布的商店详情文本。
• update-metadata 现在采用与 update-metadata-ui 相同的控制面板工作流，因此需要登录 Chrome，而不仅仅是提供 API 令牌。
• 原始的 metadata、title、summary 和 defaultLocale 输入会被拒绝并附带说明；不受支持的输入绝不会被静默忽略。
• storeIconPath 不再是受支持的上传方式。之前的通用文件输入方式无法验证更改的是哪个资源；请改为在 Developer Dashboard 中上传图标。

许可证

MIT