App Store Connect MCP Server

由 Trial and Error Inc 开发
连接 App Store Connect 和 AI 助手的可靠桥梁

问题

你需要在 Claude 中获取 iOS 应用的指标数据。官方的 MCP 服务器已损坏。手动导出数据浪费了数小时的时间。这可以解决这个问题。

解决方案

一个适用于 App Store Connect 的 MCP 服务器。仅用了 3 小时就构建完成。不依赖于任何已损坏的包。它就是这么简单。

快速开始

# 克隆仓库
git clone https://github.com/TrialAndErrorAI/appstore-connect-mcp
cd appstore-connect-mcp

# 安装依赖
npm install

# 构建
npm run build

# 配置 Claude Desktop
# 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "appstore-connect": {
      "command": "node",
      "args": ["/path/to/appstore-connect-mcp/dist/index.js"],
      "env": {
        "APP_STORE_KEY_ID": "YOUR_KEY_ID",
        "APP_STORE_ISSUER_ID": "YOUR_ISSUER_ID",
        "APP_STORE_P8_PATH": "/path/to/key.p8"
      }
    }
  }
}

# 重启 Claude Desktop

获取 App Store Connect 凭证

1. 访问 App Store Connect
2. 导航至 用户与访问权限 → 密钥
3. 点击 "+" 生成新密钥
4. 选择 "管理员" 或 "财务" 角色
5. 下载 .p8 文件（仅可下载一次！）
6. 记录你的密钥 ID 和发行人 ID

你可以向 Claude 提问的内容

配置完成后，Claude 可以帮助你：

• 财务指标："我们的 iOS 每月经常性收入是多少？"
• 订阅分析："显示活跃订阅者数量和流失率"
• 应用性能："列出我们所有 iOS 应用及其当前版本"
• 收入洞察："计算我们的年度经常性收入和增长率"
• API 健康状况："测试 App Store Connect 连接"
• 使用监控："显示 API 速率限制状态"

更多功能即将推出：崩溃分析、TestFlight 指标、客户评论

架构

详见 RFC-001-architecture.md 技术细节。

项目结构

appstore-connect-mcp/
├── PRFAQ.md               # 产品愿景和常见问题解答
├── RFC-001-architecture.md # 技术规范
├── src/
│   ├── auth/             # JWT 身份验证
│   ├── api/              # App Store Connect 客户端
│   ├── services/         # 域逻辑
│   └── server/           # MCP 服务器实现
├── tests/                # 测试套件
└── dist/                 # 编译输出

开发

# 安装依赖
npm install

# 在开发模式下运行
npm run dev

# 运行测试
npm test

# 为生产环境构建
npm run build

# 类型检查
npm run type-check

我们为什么要构建这个

我们的投资组合公司 RenovateAI 在 App Store 上的设计工具类别中排名第 28。我们需要在 Claude 中实时获取 iOS 指标数据以便做出基于数据的决策。现有的解决方案让我们失望：

• @joshuarileydev/app-store-connect-mcp-server - NPM 404 错误
• 手动 API 集成 - 多天的工作量，维护负担
• CSV 导出 - 手动操作，容易出错，耗时

所以我们自己构建了一个。干净、类型化、可靠。仅用了 3 小时。

状态

🚀 ALPHA 发布 - MVP 完成，准备测试

已完成 ✅

• 编写了 PRFAQ - 明确了愿景
• 草拟了 RFC - 定义了架构
• 身份验证模块 - 使用 P8 密钥的 JWT
• API 客户端 - 速率限制、分页、错误处理
• MCP 服务器 - 向 Claude 暴露 8 个工具
• 核心服务 - 应用和服务
• TypeScript 设置 - 完整类型安全
• 构建系统 - 清晰编译
• 文档 - 设置指南和 API 文档

正在进行中 🔄

• 使用真实 App Store Connect 账户进行实时测试
• 实现分析服务
• 综合测试套件
• 发布 npm 包

路线图 📍

• 使用 GitHub Actions 自动化测试
• 更多财务报告类型
• TestFlight 集成
• 客户评论分析
• 崩溃报告指标

当前状态：MVP 完成，等待 App Store Connect 凭证进行实时测试

许可

MIT - 使用它，修改它，出售它。只要让它工作。

可用工具

MCP 服务器向 Claude 暴露了 8 个工具：

工具	描述	状态
list_apps	获取账户中的所有应用	✅ 已准备好
get_app	获取详细的应用信息	✅ 已准备好
get_sales_report	获取销售和订阅数据	✅ 已准备好
get_revenue_metrics	计算 MRR、ARR、流失率	✅ 已准备好
get_subscription_metrics	订阅分析	✅ 已准备好
get_app_analytics	用户参与度指标	🔄 占位符
test_connection	验证 API 访问	✅ 已准备好
get_api_stats	速率限制监控	✅ 已准备好

故障排除

常见问题

1. Claude 日志中的 "意外标记" 错误

原因：控制台输出污染了 JSON-RPC 流
修复：确保生产代码中没有 console.log 语句
检查：/Users/sid/Library/Logs/Claude/mcp-server-appstore-connect.log

# 查看日志中的控制台输出
tail -f ~/Library/Logs/Claude/mcp-server-appstore-connect.log

2. "非法范围 GET" 错误

原因：Apple 的 JWT 不使用 'scope' 字段
修复：从 JWT 载荷中移除 scope，在 jwt-manager.ts 中

JWT 载荷应只包括：

{
  "iss": "ISSUER_ID",
  "iat": 1234567890,
  "exp": 1234568890,
  "aud": "appstoreconnect-v1"
}

3. MCP 无法连接

故障排查步骤：

1. 检查 Claude 配置中的凭证
2. 验证 P8 文件具有正确的权限：chmod 600 /path/to/key.p8
3. 手动测试身份验证：

   source .env && npm run test:auth
   

4. 验证 Claude Desktop 配置路径：~/Library/Application Support/Claude/claude_desktop_config.json
5. 配置更改后重启 Claude Desktop

4. 财务报告错误

常见修复：

• 添加版本参数：version: "1_4" 对于报告
• 财务数据需要供应商编号（在 App Store Connect → 支付中查找）
• 确保 API 密钥具有 "财务" 角色权限

5. 数据为空或缺失

检查：

• 应用 ID 存在且你有访问权限
• 日期范围有效（Apple 保留有限的历史数据）
• 报告对于你的地区/应用可用

6. 速率限制（429 错误）

解决方案：

• 内置指数退避应自动处理此问题
• 如果持续存在，请减少请求频率
• 检查 API 使用情况：使用 Claude 中的 get_api_stats 工具

7. 身份验证令牌过期

修复：令牌每 19 分钟自动刷新。如果问题持续存在：

# 清除任何缓存的令牌并重新启动
rm -f ~/.appstore-connect-token-cache

调试模式

启用详细日志记录：

export DEBUG=appstore-connect:*
npm start

验证命令

# 测试 P8 密钥格式
openssl pkey -in /path/to/key.p8 -text -noout

# 测试 API 连接性
curl -H "Authorization: Bearer $(npm run generate-token)" \
     https://api.appstoreconnect.apple.com/v1/apps

# 验证 Claude 配置
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

支持

• 问题：GitHub Issues
• 讨论：即将推出
• 邮件：mcp@trialanderror.ai

致谢

由 Trial and Error Inc 开发，因为不可接受的依赖关系是不可接受的。

首次生产使用：RenovateAI - 理解架构的 AI。

---

"我们不会等待包正常工作。我们自己构建。" - Trial and Error Inc

如果你觉得有用，请给这个仓库点个星！我们正在为实际使用的工具构建更多的 MCP 服务器。