google-play-developer-mcp

google-play-developer-mcp

适用于 Google Play 的完整 Model Context Protocol（MCP）服务。 157 个工具。完整支持 Android Publisher API v3 和 Play Developer Reporting API v1beta1。不含已弃用的端点。可与 Claude、Cursor、VS Code Copilot、Gemini CLI 或任何 MCP 客户端配合使用。

另请参阅： app-store-connect-mcp — 为 Apple 的 App Store Connect 秉持同样的理念。

---

目录

• 为何开发此项目
• 功能矩阵
• 快速开始
• 分步设置
• 向 MCP 客户端注册
• 使用示例
• 工具参考
• 安全性
• 设计说明
• 参与贡献
• 版本历史
• 参考资料

---

为何开发此项目

Google Play Console 提供 API，但其覆盖范围广、变化快。现有的社区 MCP 各自只覆盖一部分——有的处理商店商品详情，有的处理版本发布，还有的处理评价——而且都跟不上 Google 的弃用节奏。

google-play-developer-mcp 是一个能覆盖所有内容的服务。

属性	此服务	常见社区 MCP
Android Publisher API v3	✅ 完整支持	部分支持
Play Developer Reporting API	✅ 完整支持	❌ 缺失
monetization.onetimeproducts（2025 年后的商品目录）	✅	使用已弃用的 inappproducts
purchases.subscriptionsv2 / productsv2	✅	通常仍使用 v1
2026 年功能（OfferPhase、取消/延期、priceStepUp）	✅	❌
多账户	✅	通常仅支持一个
凭据安全	仓库中不存放密钥，严格配置 .gitignore	各不相同
按 semver 公开发布	✅ v1.0.0	大多尚未达到 1.0

如果你使用 AI 助手操作 Google Play Console——自动发布、评价分流、订阅商品目录管理、崩溃分流——安装此服务后，助手就能获得一整套工具。

---

功能矩阵

涵盖 33 个组的 157 个工具。支持两个 API 中所有未弃用的端点。

Android Publisher API v3

| 分组 | 工具 | 涵盖内容 | |---|---|---| | `accounts_*` | 6 | 本地注册表 — 添加 / 列出 / 切换 / 移除 / 更新多个 Play Console 账号 | | `auth_*` | 1 | 验证服务账号能否获取令牌 | | `apps_*` | 2 | 列出服务账号可见的所有应用，获取应用详情 | | `edits_*` | 5 | 托管发布事务：`insert`、`get`、`validate`、`commit`、`delete` | | `details_*` | 3 | 应用级联系邮箱 / 电话 / 网站、默认语言 | | `country_availability_*` | 1 | 编辑中的国家/地区可用性 | | `listings_*` | 6 | 各语言区域的标题 / 简短说明 / 完整说明 / 视频。包含 `delete_all` | | `images_*` | 4 | 图标、功能图片、宣传图片、手机 / 平板电脑 / 电视截图。列出、上传、删除、全部删除 | | `bundles_*` | 2 | 上传和列出 Android App Bundle（AAB） | | `apks_*` | 3 | 上传 / 列出 APK + 注册外部托管的 APK（企业版） | | `deobfuscation_files_*` | 1 | 上传 ProGuard / 原生代码映射文件 | | `expansion_files_*` | 4 | OBB — 获取 / 上传 / 更新 / 修补 | | `tracks_*` | 5 | `internal`、`alpha`、`beta`、`production`，以及自定义封闭式测试轨道。列出、获取、更新、修补、创建 | | `testers_*` | 3 | 用于内部 / 封闭式测试轨道的 Google 群组许可名单 | | `onetime_products_*` | 17 | ✨ 面向非订阅产品的全新变现目录。三级层级：产品 → 购买选项 → 优惠。三个层级均支持完整的 CRUD + 批量操作 | | `subscriptions_*` | 8 | 订阅目录：列出、创建、更新、删除、归档、批量获取、批量更新 | | `subscription_base_plans_*` | 7 | 月度 / 年度计划。启用、停用、迁移价格、批量迁移、批量更新 + 状态 | | `subscription_offers_*` | 10 | 免费试用 / 入门价格。创建、更新、删除、启用、停用 + 各类批量操作 | | `monetization_convert_region_prices` | 1 | 根据一个输入价格计算可比的地区价格 | | `purchases_products_v2_*` | 1 | 验证一次性产品购买（支持多个购买选项 + 优惠） | | `purchases_products_*` | 2 | 确认 / 消耗一次性购买（`productsv2` 仅提供 `get`） | | `purchases_subscriptions_v2_*` | 4 | 获取、撤销、取消、延期。包含 2026 年的 `OfferPhase`、`outOfAppPurchaseContext`、价格阶梯调整同意、基于商品项的退款 | | `purchases_subscriptions_acknowledge` | 1 | v1 确认（保留 — 确认首次购买时仍应使用此调用） | | `purchases_voided_list` | 1 | 退款 / 拒付信息流 | | `orders_*` | 5 | 列出、获取、批量获取、退款、审核退款（获取 + 批量获取于 2025-05 新增；`review_refund` 于 2026-07 新增，用于协同拒付） | | `external_transactions_*` | 3 | 替代结算（韩国 / 欧盟）— 获取 / 创建 / 退款 | | `reviews_*` | 3 | 列出、获取、回复 | | `users_*` + `grants_*` | 7 | 团队成员和按应用授予的权限 | | `device_tier_configs_*` | 3 | AAB 的设备层级定位 | | `app_recovery_*` | 5 | 恢复操作：列出、创建、部署、取消、添加定位 | | `generated_apks_*` | 2 | 列出并下载由 AAB 生成的 APK | | `system_apks_variants_*` | 4 | 用于预加载场景的系统 APK 变体 | | `internal_app_sharing_*` | 2 | 上传 APK 或 AAB，以便通过内部链接分享 |

Play 开发者报告 API v1beta1

| 分组 | 工具 | 涵盖内容 | |---|---|---| | `reports_apps_*` | 2 | `search`、`fetch_release_filter_options` | | `reports_anomalies_list` | 1 | 所有指标集中的已检测异常 | | `reports_crash_rate_*` | 2 | 崩溃率——元数据 + 时间序列查询 | | `reports_anr_rate_*` | 2 | ANR 率 | | `reports_slow_start_rate_*` | 2 | 启动缓慢（冷启动） | | `reports_slow_rendering_rate_*` | 2 | 渲染缓慢（卡顿） | | `reports_excessive_wakeup_rate_*` | 2 | 电池——过度唤醒 | | `reports_stuck_background_wake_lock_rate_*` | 2 | 电池——卡住的唤醒锁 | | `reports_lmk_rate_*` | 2 | 低内存杀手触发率 | | `reports_anon_rss_swap_memory_*` | 2 | 匿名 RSS + 交换内存用量 | | `reports_bitmap_memory_*` | 2 | 位图内存用量 | | `reports_errors_counts_*` | 2 | 错误总数 | | `reports_errors_issues_search` | 1 | 按组搜索 ErrorIssue | | `reports_errors_reports_search` | 1 | 搜索原始 ErrorReport |

---

快速开始

npm install -g google-play-developer-mcp

然后在 MCP 客户端配置中（例如 ~/.config/claude/config.json、Cursor MCP 配置或 VS Code mcp.json）：

{
  "mcpServers": {
    "google-play-developer": {
      "command": "google-play-developer-mcp"
    }
  }
}

接下来，告知服务要使用哪个 Play Console 账号——请参阅下方的分步设置指南。

---

分步设置

1. 创建 Google Cloud 服务账号

1. 打开 Google Cloud Console。
2. 选择或创建一个项目（任何项目均可——服务账号仅存放在此项目中）。
3. API 和服务 → 库——启用以下两项：
   • Google Play Android Developer API
   • Google Play Developer Reporting API
4. IAM 和管理 → 服务账号 → 创建服务账号。
5. 创建后，打开该账号 → 密钥 → 添加密钥 → JSON。下载 JSON 文件。
6. 将 JSON 文件移至安全位置，并确保不在任何 git 仓库中。建议存放于：~/.config/google-play-developer-mcp/service-account.json。

2. 在 Play Console 中授权服务账号

1. 打开 Play Console。
2. 用户和权限 → 邀请新用户。粘贴服务账号邮箱（格式类似 [email protected]）。
3. 分配权限：
   • 管理员（所有权限），以获得完全访问权限。
   • 或选择范围更窄的权限组合（查看应用信息、管理商店展示信息、管理订单和订阅等），以限制 MCP 可执行的操作。
4. **最多等待 24 小时。**Play Console 需要时间传播新授权——这是一个常见问题。如果早期 API 调用返回 PERMISSION_DENIED，通常就是这个原因。

3. 将账号注册到 MCP 服务

启动已配置该服务的任意 MCP 客户端，然后运行：

accounts_add --name my-app \
  --keyFile /Users/you/.config/google-play-developer-mcp/service-account.json \
  --description "My company's Play Console"

（或者手动创建 ~/.google-play-developer-mcp/accounts.json——请参阅下方的文件格式。）

4. 验证

auth_status

应返回 { ok: true, email: "..." }。

apps_list

列出该服务账号可查看的应用。

---

在 MCP 客户端中注册

Claude Desktop

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-play-developer": {
      "command": "google-play-developer-mcp"
    }
  }
}

Claude Code

claude mcp add google-play-developer google-play-developer-mcp

或者编辑 ~/.claude.json：

{
  "mcpServers": {
    "google-play-developer": {
      "command": "google-play-developer-mcp"
    }
  }
}

Cursor

设置 → MCP → 添加新的 MCP 服务：

{
  "google-play-developer": {
    "command": "google-play-developer-mcp"
  }
}

VS Code（GitHub Copilot Agent 模式）

.vscode/mcp.json：

{
  "servers": {
    "google-play-developer": {
      "type": "stdio",
      "command": "google-play-developer-mcp"
    }
  }
}

Gemini CLI / Codex CLI / Windsurf / Continue

任何兼容 MCP 的客户端都接受相同的 command 条目——将其指向全局安装的 google-play-developer-mcp 二进制文件（如果从源代码运行，则指向 node /path/to/dist/index.js）。

从源代码运行（无需 npm install -g）

git clone https://github.com/devinwang/google-play-developer-mcp.git
cd google-play-developer-mcp
npm install
npm run build

然后在 MCP 客户端配置中：

{
  "mcpServers": {
    "google-play-developer": {
      "command": "node",
      "args": ["/absolute/path/to/google-play-developer-mcp/dist/index.js"]
    }
  }
}

---

用法示例

将新构建版本发布到内部测试

accounts_switch --name my-app

# Open an edit, upload bundle, route it to the internal track, commit.
edits_insert --packageName com.example.app
# → { id: "EDIT_ID", expiryTimeSeconds: "..." }

bundles_upload --packageName com.example.app --editId EDIT_ID \
  --file /path/to/app-release.aab
# → { versionCode: 47, sha256: "..." }

tracks_update --packageName com.example.app --editId EDIT_ID \
  --track internal \
  --releases '[{"versionCodes":["47"],"status":"completed","releaseNotes":[{"language":"en-US","text":"Fixes a crash on startup."}]}]'

edits_commit --packageName com.example.app --editId EDIT_ID

通过分阶段发布将 Beta 版本提升为正式版

edits_insert --packageName com.example.app
# → EDIT_ID

# Promote the beta versionCodes to production with 10% staged rollout.
tracks_update --packageName com.example.app --editId EDIT_ID \
  --track production \
  --releases '[{"versionCodes":["47"],"status":"inProgress","userFraction":0.1}]'

edits_commit --packageName com.example.app --editId EDIT_ID

回复评价

reviews_list --packageName com.example.app --maxResults 50
# → { reviews: [{ reviewId, authorName, comments, ... }] }

reviews_reply --packageName com.example.app --reviewId REVIEW_ID \
  --replyText "Thanks for the feedback! The crash is fixed in v1.2 — please update."

创建包含免费试用优惠的订阅

# 1. Create the subscription (product)
subscriptions_create --packageName com.example.app --productId plus_monthly \
  --subscription '{"listings":[{"languageCode":"en-US","title":"Plus","benefits":["All premium features"]}],"taxAndComplianceSettings":{"taxTier":"TAX_TIER_UNSPECIFIED"}}'

# 2. Create a base plan
subscription_base_plans_batch_update --packageName com.example.app --productId plus_monthly \
  --requests '[{"basePlan":{"basePlanId":"monthly","autoRenewingBasePlanType":{"billingPeriodDuration":"P1M","accountHoldDuration":"P30D"},"state":"DRAFT","regionalConfigs":[{"regionCode":"US","price":{"currencyCode":"USD","units":"9","nanos":990000000}}]},"updateMask":"autoRenewingBasePlanType,regionalConfigs"}]'

# 3. Activate the base plan
subscription_base_plans_activate --packageName com.example.app \
  --productId plus_monthly --basePlanId monthly

# 4. Create a 7-day free-trial offer
subscription_offers_create --packageName com.example.app --productId plus_monthly \
  --basePlanId monthly --offerId new-user-trial \
  --offer '{"phases":[{"duration":"P7D","regionalConfigs":[{"regionCode":"US","free":true}]}],"state":"DRAFT"}'

subscription_offers_activate --packageName com.example.app \
  --productId plus_monthly --basePlanId monthly --offerId new-user-trial

在服务器端验证购买令牌（后端用例）

# For a one-time product (consumable or non-consumable)
purchases_products_v2_get --packageName com.example.app --token PURCHASE_TOKEN

# For a subscription — includes 2026 OfferPhase, priceChangeState, etc.
purchases_subscriptions_v2_get --packageName com.example.app --token PURCHASE_TOKEN

诊断崩溃

reports_crash_rate_query \
  --name "apps/com.example.app/crashRateMetricSet" \
  --dimensions '["versionCode","countryCode"]' \
  --metrics '["crashRate","distinctUsers"]' \
  --timelineSpec '{"aggregationPeriod":"DAILY","startTime":{"year":2026,"month":4,"day":1},"endTime":{"year":2026,"month":4,"day":8}}'

reports_errors_issues_search --parent "apps/com.example.app" \
  --filter "errorIssueType = \"CRASH\""

---

工具参考

所有工具都使用遵循 resource_action 约定的 snake_case 名称，与 Android Publisher URL 结构保持一致。完整的分组说明请参阅功能矩阵。

每个工具都接受一个 JSON 参数对象——请从 MCP 客户端查看架构（Claude Code：/mcp tools，Claude Desktop：在聊天中显示工具列表，Cursor：MCP 面板），了解确切的结构。

复杂的正文参数（例如 subscription、offer、appRecoveryAction、订阅 releases）直接接受 Google 文档中定义的 JSON 架构——请参阅官方参考文档。

---

安全

此仓库不包含任何凭据。你需要提供服务账号 JSON 密钥；服务只会记录其路径。

磁盘上存放和不存放的内容：

位置	内容
~/.google-play-developer-mcp/accounts.json	账号名称、密钥文件路径和描述。不含机密信息。创建时权限为 0600。
~/.config/…/service-account.json（由你放置）	实际的 Google Cloud 服务账号 JSON。绝不提交。任何工具都不会将其输出。
仓库内容	仅包含代码。

.gitignore 规则

• *.json.key、*service-account*.json、*service_account*.json、*-sa.json、*-sa-key.json
• gcp-key*.json、google-credentials*.json、play-credentials*.json
• .env、.env.*（但会保留 .env.example）
• accounts.json、credentials/、keys/、secrets/
• *.pem、*.p12、*.pfx、*.key、id_rsa*

建议的安全习惯

• 将服务账号 JSON 保存在计算机上所有 git 仓库之外。
• 仅向服务账号授予工作流所需的最小权限角色。完整管理员权限会允许 MCP 删除应用元数据——只授予所需权限即可。
• 每年轮换一次服务账号密钥：在 Google Cloud Console 中删除旧密钥，创建新密钥，然后运行 accounts_update --keyFile <newPath>。
• auth_status 绝不会返回实际令牌；只返回布尔值和服务账号邮箱。

审计记录

Android Publisher API 上的每次写入操作都会由 Google Cloud IAM 以服务账号的身份记录。如果怀疑有人滥用权限，Cloud Console 中的IAM → Audit Logs会显示调用过哪些端点。

---

设计说明

• 感知编辑会话。 Android Publisher API 上的每次写入操作都会在编辑中执行。服务会直接公开 edits_insert / edits_commit / edits_delete，因此你可以在多次工具调用期间保持编辑开启——这是最常见的多步骤工作流。如果忘记提交，就不会发布任何内容。默认安全。
• 多账号。 一个服务进程可以管理多个 Play Console 账号。使用 accounts_switch 切换账号。状态存储在 ~/.google-play-developer-mcp/accounts.json 中。
• 不使用已弃用的端点。 目录端点使用 monetization.onetimeproducts（而非已弃用的 inappproducts）。购买验证使用 purchasesV2 / subscriptionsV2。
• 类型具备前向兼容性。 如果 Google 发布 API 功能的速度快于 googleapis TypeScript 类型定义的更新速度，我们会通过 publisherAny() / reportingAny() 进行类型转换。HTTP 调用完全相同——仅跳过已知存在偏差的部分所对应的 TypeScript 静态检查。
• 错误消息清晰易懂。 所有 Google API 错误都会转换为易懂的消息——401 表示“令牌错误”，403 表示“权限尚未生效，请等待 24 小时”，429 表示“配额已用尽”，等等。
• 无状态传输。 服务通过 stdio 运行，不监听网络，也不会在账号文件之外持久保存状态。
• 零遥测。 服务绝不会主动连接外部服务器。

---

贡献

欢迎提交 PR。提交前请确认：

• npm run typecheck 通过（CI 也会运行此检查）
• 切勿在 issue 或 PR 中包含服务账号密钥或令牌。如需分享复现信息，请将令牌脱敏（X-Goog-Api-Client: ...REDACTED...）。
• 新工具遵循 resource_action 命名约定。
• 如果添加了调用新 API 范围的工具，请将其加入功能矩阵，确保文档保持同步。

---

版本历史

0.2.0 — 2026-10-21

• 157 个 MCP 工具（+7）。新增：orders_review_refund、purchases_products_acknowledge、purchases_products_consume、reports_anon_rss_swap_memory_{get,query}、reports_bitmap_memory_{get,query}。
• 将 googleapis 从 171 升级至 187。

0.1.0 — 2026-04-20（首次公开发布）

• 150 个 MCP 工具，涵盖完整的 Android Publisher API v3 和 Play Developer Reporting API v1beta1。
• 仅使用最新一代端点。 使用 monetization.onetimeproducts（取代已弃用的 inappproducts）、purchases.productsv2 / subscriptionsv2（取代 v1）。
• 2026 年功能。 SubscriptionPurchaseV2.offerPhase、purchases.subscriptionsv2.cancel/defer、orders.batchGet、offerPhaseDetails、价格阶梯升级同意、outOfAppPurchaseContext。
• 支持多账号，并提供磁盘注册表。
• 仓库中不含任何凭据。提供全面的 .gitignore。
• 针对所有常见 Google API 故障模式进行错误转换。

---

参考资料

• Google Play Android Developer API v3 — REST 参考
• Play Developer API 发行说明
• Play Developer Reporting API v1beta1 — REST 参考
• monetization.onetimeproducts 参考
• purchases.subscriptionsv2 参考
• Model Context Protocol 规范
• Anthropic Claude MCP 文档

---

许可证

MIT — 详见 LICENSE。