跳到主要内容
AI教程

使用 Mağaza MCP 管理 App Store Connect 和 Google Play

了解如何安装 Mağaza MCP，安全连接 Apple 和 Google 凭据，使用自然语言查询两个应用商店，比较订阅、诊断购买问题、访问高级 API 操作，并启用只读保护措施。

AI我搜编辑部阅读约 14 分钟
使用 Mağaza MCP 管理 App Store Connect 和 Google Play

什么是 Mağaza MCP？

Mağaza MCP 是一个开源的模型上下文协议服务器，让 AI 助手通过一次安装即可访问 App Store Connect 和 Google Play。它面向需要检查、比较和管理 iOS 与 Android 商店数据的开发者及应用运营人员，无需在不同集成之间切换。

服务器在你的本地计算机上运行，并直接与 Apple 和 Google 通信。整个过程没有中间服务。Apple 工具使用 appstore__ 前缀，Google Play 工具使用 play__ 前缀，跨商店或通用 API 工具使用 magaza__ 前缀。

它的独特之处在于能够通过一次操作回答跨商店问题。例如，你的助手可以比较同一订阅在 App Store 和 Google Play 上的土耳其价格，配对对应的 iOS 和 Android 应用，或调查两个商店中的应用内购买配置问题。

主要功能

  • 一个 MCP 服务器连接两个商店：连接 App Store Connect、Google Play，或同时连接两者。
  • 跨商店工作流：比较订阅、生成综合应用概览，并诊断两个平台上的应用内购买配置问题。
  • 27 个专用工具：双商店安装提供 27 个工具，用于常见商店操作和通用 API 访问。
  • 完整 API 覆盖：搜索并调用 App Store Connect API v4.5、Android Publisher API v3 和 Play Developer Reporting API v1beta1 中的 1,440 个操作。
  • 较低的上下文开销：完整 API 目录通过搜索和分发工具访问，而不是将全部 1,440 个操作分别公开为 MCP 工具。
  • 本地凭据存储：在可用时，凭据会保存在 macOS 钥匙串中；在无法使用钥匙串的系统上，则回退到权限受限的文件存储。
  • 写入操作需要确认：更改数据的操作需要明确确认 onayla=true。
  • 只读模式：可以将写入工具完全从模型的工具列表中移除。
  • 无遥测：项目不会发送分析数据、错误报告或使用数据。

前置要求

运行此软件包前，请安装 Node.js 18 或更高版本。你还需要为每个希望连接的商店准备相应的凭据。

App Store Connect 要求

创建一个 App Store Connect API 密钥，并在设置期间准备好其 Key ID、Issuer ID 和 .p8 文件。对于大多数操作，App Manager 角色已足够。用户与访问管理端点以及部分分析报告可能需要更高权限。

该密钥必须是 App Store Connect API 密钥。不能使用 StoreKit 密钥或推送通知密钥替代。

Google Play 要求

  1. 通过 Play Console → Users and permissions 邀请服务账号，然后授予其访问相关应用的权限。
  2. 在关联的 Google Cloud 项目中启用 Android Publisher API 和 Play Developer Reporting API。

Reporting API 不仅用于崩溃指标，也用于应用发现。Android Publisher API 没有列出账号所有可用应用的端点。

无法通过这些 API 读取合同、税务详情和银行信息。Apple 不会通过 App Store Connect API 密钥公开这些信息。

安装 Mağaza MCP

使用一条命令启动交互式安装程序：

npx magaza-mcp kur

向导会引导你完成以下步骤：

  1. 选择 App Store Connect、Google Play，或两个商店。
  2. 输入 App Store Connect Key ID 和 Issuer ID，然后提供 .p8 文件的路径。
  3. 提供 Google Play 服务账号 JSON 文件的路径。
  4. 选择检测到的、需要安装 MCP 配置的 AI 客户端。
  5. 选择服务器是否应以只读模式运行。

安装程序会在保存凭据前，通过真实 API 请求验证 Apple 和 Google 凭据。凭据不会写入 AI 客户端的配置文件。配置中仅包含通过 MAGAZALAR 等信息指定启用哪些商店。

在 macOS 上，凭据会存储在钥匙串中。如果钥匙串不可用，项目会回退到权限为 0600 的文件。

支持的 MCP 客户端

安装程序支持 Claude Code、Claude Desktop、Antigravity、Cursor、Windsurf 和 Codex。它只更新 magaza-mcp 条目，保留无关配置，在写入前创建 .magaza-mcp-yedek 备份，并执行原子写入。

设置完成后，请重启所有已打开的客户端应用，使其加载新的 MCP 服务器。

验证安装

使用状态和工具列表命令确认结果：

npx magaza-mcp durum
npx magaza-mcp durum --json
npx magaza-mcp araclar
npx magaza-mcp surum
npx magaza-mcp yardim

durum 会报告已连接的商店，而 araclar 会列出已安装的工具。标有 ✎ 的工具可以修改商店数据。

基本用法

Mağaza MCP 旨在通过兼容 MCP 的助手使用自然语言请求。客户端重启后，先从一个简单的库存请求开始：

列出我在两个商店中的应用，并显示每个应用当前发布在哪个商店。

当两个商店都已连接时，magaza__genel_bakis 会合并应用列表，配对匹配的 iOS 和 Android 产品，并分离出仅存在于其中一个商店中的应用。

比较订阅价格

请助手比较某个国家/地区的订阅价格：

Note Keeper 在土耳其 App Store 和 Google Play 中的月度订阅费用是多少？两者有差异吗？

magaza__abonelik_karsilastir 工具会比较产品标识符、计费周期和特定国家/地区的价格。它还会将国家/地区代码转换为各商店所需的格式。

诊断购买问题

对于已付款但未获得高级访问权限的客户，可以使用如下请求：

客户表示他们已经付款，但高级访问权限尚未激活。请检查两个商店中的购买设置，并总结可能的原因。

magaza__iap_teshis 工具会检查产品是否已发布、相关国家/地区是否存在定价，以及 Google Play 是否为新订阅者提供了基础方案。如果提供 Play 购买令牌，该工具还可以在诊断过程中验证该令牌。

检查 App Store Connect

App Store 专用工具可以列出应用、版本发布、TestFlight 构建版本、评价、订阅组、订阅价格、应用内购买项目、TestFlight 群组和销售报告。请求示例包括：

  • 当前哪个 App Store 版本卡在审核中？
  • 我昨天上传的 TestFlight 构建版本处理完成了吗？
  • 总结上周的一星和二星评价。
  • 下载此应用的每日销售报告。

商店元数据和评价回复也可以修改，但这些操作需要明确确认。

检查 Google Play

Google Play 工具涵盖应用、发布轨道、评价、订阅、基础方案定价、一次性产品、购买验证、已撤销购买以及 Android vitals 崩溃率。请求示例包括：

  • 生产轨道上是哪个版本？有多少百分比的用户会收到它？
  • 过去 14 天内崩溃率是否上升？
  • 此购买令牌有效吗？订阅仍处于活动状态吗？
  • 显示可用期间内已退款或已撤销的购买。

Google 只能通过相关 API 提供大约最近一周的评价。已撤销购买数据仅限最近 30 天。

安全执行写入操作

appstore__yorum_yanitla、appstore__metin_guncelle 和 play__yorum_yanitla 等工具可以修改商店数据。它们不会在首次请求时立即执行。相反，服务器会返回拟执行的操作和预期的请求正文。

检查提案后，批准该提案，并让助手使用以下参数重复执行操作：

onayla=true

此确认机制由服务器强制执行，而不是仅依赖 MCP 客户端的界面。

启用只读模式

进行审计、报告或谨慎试验时，请以只读模式启动服务器：

npx magaza-mcp --salt-okunur

也可以设置：

SALT_OKUNUR=1

连接两个商店后，只读模式会将公开的工具列表从 27 个减少到 24 个。专用于写入的工具会消失，因此模型无法看到或调用它们。通用的 magaza__cagir 调度器仍然可用，因为读取操作也需要它，但在只读模式下会拒绝写入操作。

使用完整 API 目录

专用工具涵盖常见工作流，但 Mağaza MCP 还提供对 1,440 个 API 操作的访问。它不会将每个操作都放入模型上下文，而是提供三个通用工具：

  • magaza__endpoint_ara 搜索已连接商店的 API 目录，并返回匹配的操作名称、HTTP 方法、路径和参数。
  • magaza__sema 显示某个操作的请求正文架构，在执行 POST 或 PATCH 请求前尤其有用。
  • magaza__cagir 调用选定的操作，并自动填充路径参数。

一个实用的高级提示词是：

在已连接商店的 API 中搜索管理此资源的端点。在尝试任何写入操作前，先向我展示请求架构。

这些目录根据 Apple 官方 App Store Connect OpenAPI 规范，以及 Google Android Publisher 和 Play Developer Reporting 发现文档生成。仍是实现某项功能的唯一途径时，已弃用的 Apple 操作仍可搜索到，但其摘要会以 [ESKİMİŞ] 开头，并且在搜索结果中的排名较低。

了解工具隔离

服务器通过以下设计规则避免混用两个商店：

  • 每个商店专用工具都有明确的前缀。
  • 带有 appstore__ 前缀的工具不会调用 Google Play，带有 play__ 前缀的工具也不会调用 Apple。
  • 未选定商店的工具不会加载到内存中，也不会展示给模型。
  • 跨商店工具仅在两个商店都启用时存在。
  • 调度工具接受的 magaza 参数仅限于安装期间配置的商店。

双商店安装会加载 27 个工具。仅安装 App Store 时加载 14 个，仅安装 Play 时加载 13 个。这使 MCP 上下文与配置的环境保持一致。

高级安全提示

  • 不要将凭据粘贴到聊天中：请自行运行 npx magaza-mcp kur，并通过本地向导输入凭据路径。
  • 分析时使用只读模式：当你只需要发布、审核、定价、购买或健康状态信息时，请启用该模式。
  • 审核每一项拟执行的写入操作：在批准 onayla=true 前，确认应用、资源、区域设置和请求正文。
  • 授予最低限度的权限：在 Apple 中使用 App Manager，除非某个必需端点明确需要更高权限；将 Google 服务账号的权限限制在相关应用范围内。
  • 保持系统时间准确：Apple JWT 的有效期为 20 分钟，因此较大的时钟偏差可能导致身份验证失败。

服务器会验证并编码路径参数，拒绝 . 和 .. 等路径遍历尝试，并验证绝对 URL 的主机。网络流量仅限于 Apple API、Android Publisher API、Play Developer Reporting API 以及 Google OAuth 令牌端点。

故障排除

Apple 返回 401

请确认 Key ID、Issuer ID 和 .p8 文件属于同一个 App Store Connect API 密钥。检查设备时钟，因为时间不正确的 JWT 可能会被拒绝。同时确认该文件不是 StoreKit 密钥或推送通知密钥。

Apple 返回 403

API 密钥可能没有执行该操作所需的角色。App Manager 覆盖大多数工作流程，但用户管理和某些报告需要额外权限。无论角色如何，都无法通过 API 获取合同、税务和银行数据。

Google Play 返回 403

确认服务账号已在 Play Console 中受邀，并且有权访问目标应用。权限变更可能需要几分钟才能生效。同时确认已在 Cloud 项目中启用 Android Publisher API 和 Play Developer Reporting API。

如果失败涉及旧版 inappproducts 端点，则该应用可能使用 Google 的新产品模型。play__urunler 工具会先尝试 oneTimeProducts，必要时再回退到旧版模型，从而处理这一情况。

轨道信息显示缓慢

Google Play 通过编辑会话提供发布轨道信息。读取工具会创建会话、读取数据，然后在不提交的情况下离开，因此不会发生商店变更。此过程需要额外的 HTTP 请求，因此可能耗时更长。

开发环境设置

如需参与项目开发，请克隆代码库并安装其依赖项：

git clone https://github.com/tunaarikaya/magaza-mcp.git
cd magaza-mcp
npm install
npm run build
npm run kontrol
npm run dev

npm run build 会编译 TypeScript 源代码，npm run kontrol 会在不生成文件的情况下执行类型检查，而 npm run dev 会启动监视模式编译。

如需根据 spec/ 下的三个规范文件重新生成 API 目录，请运行：

node scripts/uret-katalog.mjs

生成的操作目录会写入 src/katalog/ 下；操作列表不应手动维护。

结语

Mağaza MCP 提供了一种实用方式，让用户通过一个兼容 MCP 的助手操作 App Store Connect 和 Google Play。其跨商店工具简化了定价比较、应用清单和购买诊断，而可搜索的完整 API 目录则涵盖了较少见的操作。本地凭据处理、确认门控、只读模式以及不收集遥测数据等特性，使其适合需要严格控制商店访问权限的工作流程。