storepilot-mcp

StorePilot

Google Play と App Store にまたがる、アプリポートフォリオ全体を扱う 1 つの MCP サーバーです。

アシスタントに尋ねてみましょう。

「Google のしきい値を超えるクラッシュ率のアプリはどれですか？」

「先月、ポートフォリオ全体でアプリごとにいくら収益がありましたか？」

「両方のストアにあるすべてのアプリについて、バージョン、評価、インストール数、収益、クラッシュを表示してください。」

「ドイツ語の説明文が 2 つのストアで食い違っています。どこが違いますか？」

「Play の内部テストトラックと TestFlight に 3.2.1 をリリースしてください。」

上記の各質問は、所有するすべてのアプリを対象とする 1 回のツール呼び出しで処理できます。ツールがエンドポイント単位ではなく、ポートフォリオ単位で設計されているためです。最後の質問だけは、意図的に 2 回の呼び出しが必要です。書き込み操作は最初にプレビューを表示し、人間の確認を待ちます。

ご自身のデベロッパーアカウント（Google Play サービスアカウント、App Store Connect API キー、またはその両方）が必要です。StorePilot はアカウントを読み取りますが、公開されているストアの掲載情報をスクレイピングすることはありません。

ステータス：初期段階です。 読み取りツールは両方のストアで実アカウントを使って実行されていますが、収益とクラッシュしきい値の処理では、まだ実データを取得できていません。また、ストアに対する書き込み操作が実行されたことはありません。数値を信頼する前に、ステータスと正直な制限事項をお読みください。

---

実際に異なる点

両方のストアを、1 組のツールで扱えます。 Google Play は Android Publisher API、Play Developer Reporting API、非公開の Cloud Storage レポートバケット経由で、App Store は App Store Connect 経由で操作できます。ツールは合計 34 個で、一貫した命名になっています。

多くのツールでは取得できないインストール数と収益。 Play のインストール数、評価、収益には REST API がありません。これらは非公開の Cloud Storage バケットに UTF-16 CSV としてのみ保存されているため、多くのツールでは対象外となり、「このアプリの収益はいくらですか？」という質問には回答できません。StorePilot はそのバケットを読み取り、CSV の列を位置ではなく名前で特定し、通貨をまたいで合算することなく、通貨ごとに収益を報告します。（この処理は実装済みで、フィクスチャによるテストも行われていますが、実際のレポートはまだ読み取っていません。ステータスをご覧ください。）

ポートフォリオを最優先。 portfolio_overview は、両方のストアにあるすべてのアプリを 1 つの表に表示します。play_portfolio_health は Play アカウント全体をスキャンします。どちらもパッケージ名を指定する必要はありません。個人開発者、アプリ開発会社、代理店向けに設計されています。

クロスストアツール。 parity_check は、2 つのストア間で掲載情報やバージョンの不一致を検出します。compare_reviews は両方のストアのレビューを並べて表示します。release_both は同じバージョンを両方のストアにリリースします。metadata_pull / metadata_push は fastlane 独自のディレクトリ構成を使うため、StorePilot を導入しても fastlane を手放す必要はありません。

書き込み操作には制限があります。 すべての書き込み操作では、まずプレビューが表示されます。続いて、操作の内容に HMAC で結び付けられた、1 回限り有効で 10 分後に期限切れとなる確認トークンが返されます。本番リリースは段階的なロールアウトに限定され、上限は 20% です。

setup_doctor。 ここでの認証情報の設定には、複数の手順からなる Google Cloud、Play Console、App Store Connect の複雑な作業があり、気付きにくい失敗要因もいくつかあります。このツールは各手順を確認し、具体的な修正方法を表示します。

---

インストール

Python 3.11 以降が必要です。

uvx storepilot          # no install; uv fetches it per run

または、次のコマンドでインストールできます。

pipx install storepilot   # or: pip install storepilot

どちらの方法でも storepilot バイナリを利用できます。以下のクライアント設定には絶対パスが必要です。which storepilot を実行すると、絶対パスが表示されます。

Claude Code

claude mcp add storepilot -- storepilot

Claude Desktop / 任意の MCP クライアント

claude_desktop_config.json：

{
  "mcpServers": {
    "storepilot": {
      "command": "/absolute/path/to/storepilot",
      "env": {
        "STOREPILOT_GOOGLE_CREDENTIALS": "/path/to/service-account.json",
        "STOREPILOT_GOOGLE_REPORTS_BUCKET": "pubsite_prod_rev_0123456789",
        "STOREPILOT_ASC_KEY_PATH": "/path/to/AuthKey_XXXXXXXXXX.p8",
        "STOREPILOT_ASC_KEY_ID": "XXXXXXXXXX",
        "STOREPILOT_ASC_ISSUER_ID": "00000000-0000-0000-0000-000000000000",
        "STOREPILOT_ASC_VENDOR_NUMBER": "80000000"
      }
    }
  }
}

Cursor

Settings → MCP → Add new MCP server を選択するか、~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "storepilot": {
      "command": "/absolute/path/to/storepilot",
      "env": { "STOREPILOT_ASC_KEY_PATH": "/path/to/AuthKey_XXXXXXXXXX.p8" }
    }
  }
}

Codex CLI

~/.codex/config.toml に追加します：

[mcp_servers.storepilot]
command = "/absolute/path/to/storepilot"
env = { STOREPILOT_ASC_KEY_PATH = "/path/to/AuthKey_XXXXXXXXXX.p8" }

使用するストアのみを設定してください。各アダプターはそれぞれ独立してツールを登録し、クロスストアツールはどちらかのストアを設定すると登録されます。コードが読み取るすべての変数については、.env.example を参照してください。

.env ファイルも使用できますが、読み込まれるのはプロセスの作業ディレクトリです。つまり、リポジトリではなく、MCP クライアントがサーバーを起動したディレクトリです。チェックアウトから storepilot を自分で実行する場合は .env を使用し、それ以外の場合はクライアントの env ブロックを使用してください。

認証情報は環境変数から読み込まれ、StorePilot がどこかに書き込むことはありません。サービスアカウント JSON と .p8 はリポジトリの外に置き、どちらも chmod 600 を実行してください。これらは秘密鍵です。

---

setup_doctor から始める

データツールを呼び出して、何も返ってこない理由を推測するところから始めないでください。まず、アシスタントに setup_doctor の実行を依頼してください。認証情報の各手順を個別に確認するため、1つの失敗によってほかの問題が隠れることはなく、すべての失敗に個別の対処方法が示されます。

まだ何も設定していない場合：

StorePilot setup check
============================================================

-- Google Play ----------------------------------------------
[skip] Google Play: not configured
      Fix: Set STOREPILOT_GOOGLE_CREDENTIALS to the path of a service account JSON key. Full
      setup: create a Google Cloud project, enable the Android Publisher and Play Developer
      Reporting APIs, create a service account, download its JSON key, then invite the service
      account email in Play Console -> Users and permissions.
      Docs: https://developers.google.com/android-publisher/getting_started

-- App Store Connect ----------------------------------------
[fail] ASC credentials: App Store Connect is not configured: STOREPILOT_ASC_KEY_PATH,
      STOREPILOT_ASC_KEY_ID, STOREPILOT_ASC_ISSUER_ID unset.
      Fix: In App Store Connect go to Users and Access -> Integrations -> App Store Connect
      API, create a team key with the Admin or App Manager role, and download the .p8 file
      (Apple lets you download it exactly once). Then set STOREPILOT_ASC_KEY_PATH to that
      file, STOREPILOT_ASC_KEY_ID to the Key ID column, and STOREPILOT_ASC_ISSUER_ID to the
      Issuer ID shown above the key table. Sales reports additionally need
      STOREPILOT_ASC_VENDOR_NUMBER from Payments and Financial Reports.
      Docs: https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api
[skip] ASC token: cannot test until the credentials load
      Fix: Fix the step above, then re-run setup_doctor.
[skip] ASC API reachable: cannot test until the credentials load
      Fix: Fix the step above, then re-run setup_doctor.
[skip] ASC sales access: cannot test until the credentials load
      Fix: Fix the step above, then re-run setup_doctor.

============================================================
Summary: 1 fail, 4 skip
Resolve the [fail] items above, then run setup_doctor again.

成功に見えてしまう失敗も検出します。レビューへの返信権限がない場合、Play のレビュー API はエラーではなく HTTP 200 と空のリストを返すため、「このアプリにはレビューがない」と「必要な権限がない」は同じ応答になります。setup_doctor は推測するのではなく、この曖昧さを独立した診断として報告します。

両方のストアの詳しい手順については、docs/SETUP.md を参照してください。

---

ツール

ツールは34個あります。引数、戻り値の形式、ツールごとの制限については、docs/TOOLS.md を参照してください。

Google Play — 読み取り

ツール	確認できる内容
play_list_apps	このインストールでアクセスできるパッケージ
play_get_vitals	Google のしきい値 1.09%／0.47% と比較したクラッシュ率および ANR（アプリケーション無応答）率
play_get_anomalies	Google 独自の異常検出で検出された内容
play_get_stats	1か月分のインストール数と評価（GCS バケット）
play_get_earnings	通貨別の1か月分の収益（GCS バケット）
play_list_reviews	最近の本番環境のレビュー。星評価で絞り込み可能
play_portfolio_health	すべてのアプリのバイタル、評価、インストール数を1つの表に表示

Google Play — 書き込み（すべてゲート対象）

ツール	機能
play_upload_bundle	.aab をアップロードして、トラックにリリースします
play_create_release	アップロード済みのバージョンコードをリリースします
play_promote_release	ビルドをトラック間で移動します（ベータ版 → 本番環境）
play_expand_rollout	段階的なロールアウトの範囲を広げます。100% にする唯一の方法です
play_halt_rollout	ロールアウトを即時に停止します。確認手順はありません
play_reply_review	公開のデベロッパー返信を投稿します
play_update_listing	1つのロケールのストア掲載文を上書きします

App Store Connect

ツール	機能
asc_list_apps	キーから参照できるアプリと Apple ID
asc_list_builds	TestFlight のビルドと3つの審査ステータス
asc_list_reviews	顧客レビュー。絞り込み可能で全履歴を取得
asc_list_versions	バージョン、審査ステータス、段階的リリースの日数
asc_get_sales	売上と収益。キャッシュを長時間保持
asc_get_analytics	Apple の非同期レポート処理を介した App Analytics
asc_upload_build	Transporter の手順を返します。アップロード可能な API はありません
asc_reply_review	デベロッパーの公開返信（ゲート対象）
asc_update_metadata	編集可能なバージョンのストア掲載文（ゲート対象）
asc_submit_for_review	事前チェック後に App Review に提出します（ゲート対象）

クロスストア

ツール	機能
portfolio_overview	両ストアのすべてのアプリを1つの表に表示します
compare_reviews	1つのアプリに対する両ストアのレビューを並べて表示します
parity_check	ストア間のバージョンと掲載情報の差異を確認します
release_both	1つのバージョンをPlayとTestFlightにリリースします（トークンは1つ、要承認）
metadata_pull	ストアの掲載情報 → fastlane-layout形式のローカルツリー
metadata_push	ローカルツリー → 両ストア（要承認）
list_app_pairs	ペアの登録内容を表示します
suggest_app_pairs	バンドルIDと名前の情報からペアを提案します
pair_apps	1つのペアを登録します

さらに、setup_doctorもあります。

どちらのAPIにも、PlayのパッケージとApple IDが同じ製品であることを示す情報はありません。 そのため、ペア情報は~/.storepilot/apps.tomlに保存されます。まずsuggest_app_pairsを実行し、同意できる提案についてpair_appsを実行してください。提案は書き込まれるまで何も起こしません。間違ったペアを登録すると、一方のアプリの収益、レビュー、クラッシュ率が別のアプリに帰属してしまいますが、後続の処理では誤りに気づけません。

---

安全性モデル

書き込み操作はすべて2回の呼び出しで行います。1回目はプレビューとトークンを返し、2回目はそのトークンを渡します。

実際の安全対策はプレビューです。プレビューはチャットに表示されるため、人が「対象のアプリが違う」や「本番トラックだ」と確認できます。Playのプレビューは推定ではありません。使い捨てのPlay編集内で操作を実際に実行し、検証した後に削除するため、プレビューにはGoogleが実際に割り当てたバージョンコードと、Googleが実際に返すエラーが表示されます。

トークンは、プレビューと確定の間にずれが生じるのを防ぐためだけに使われます。操作の正規化されたフィンガープリントに対するHMACで、ツールの出力には含まれないインストールごとのシークレットを鍵とし、1回限り有効で、有効期間は10分です。単純なコンテンツハッシュでは、モデル自身が計算できてしまい、人が確認する必要のあるプレビューを表示せずにモデルが自ら確定できてしまいます。引数を1つでも変更すると、トークンは使えなくなります。

さらに、次の3つのルールがあります。

• 本番環境へのリリースは、必ず段階的ロールアウトとなり、最初の段階は最大20%に制限されます（割合を省略した場合は0.1）。 100%まで拡大できるのはplay_expand_rolloutだけです。副作用として実行されることがないよう、別の操作になっています。
• play_halt_rolloutは意図的に承認不要です。 問題のあるリリースを止めるのは常に安全な方向であり、インシデント発生中に2回目のやり取りを求める設計は失敗です。
• すべての操作を監査します。 プレビュー、確定、却下、実行、失敗のすべてを、認証情報と長い値を伏せたうえで、追記専用ログ~/.storepilot/audit.logに記録します。

release_bothは両ストアに対して1つのトークンを発行します。2つのストアへのリリースの片方だけを承認しても、リリースを承認したことにはならないためです。一部で失敗した場合は、どこに何が反映されたかを正確に示し、ロールバックはしません。もう一方のストアでAPIエラーが返ったからといって、正常に動作するビルドをユーザーから取り下げるほうが、ストア間に差異が残るよりも問題だからです。

---

ステータスと正直な制限事項

StorePilot は、両ストアの実アカウントに対して読み取り専用で実行されています。最初の実行で 3 件のバグが見つかり、すべて修正済みです。Apple は appStoreVersions エンドポイントでの sort を拒否すること、Play のレポート用バケット名は必ずしも pubsite_prod_rev_* ではないこと、バケットへのアクセスに必要なのは、エラーメッセージが推奨していた Cloud Console の IAM 権限ではなく、アカウントレベルの Play Console 権限であることです。

実環境で検証済み — サービスアカウントと ES256 JWT による認証、レート制限に合わせた呼び出し間隔の調整、両ストアでの setup_doctor、Play と App Store の読み取りツール、そして両ストアの 6 つのアプリを 1 つの表に表示する portfolio_overview。

未検証の項目があり、そのうち 2 つは重要な主張に関わります。

• バイタルのデータポイントが返されたことは一度もありません。 Android Vitals は、1 日あたりのユーザー数が最低数に満たない場合、指標を非表示にします。テストアカウントのアプリはこの数を下回っています。そのため、しきい値の比較、つまり play_get_vitals が存在する目的の機能は、実際の数値で一度も動作していません。未解決の疑問もそのままです。Reporting API は 1.09 を返すのでしょうか、それとも 0.0109 でしょうか。この不一致があると、判定がすべて 100 倍ずれます。
• レポート CSV が読み込まれたことは一度もありません。 インストール数、評価、収益はすべて GCS バケットから取得されますが、パーサーが確認したのはテスト用データだけです。Google は 2026 年 7 月に収益レポートの Fee Description 列を変更したため、実際のヘッダーがリスク要因です。

• 書き込み処理が実行されたことは一度もありません。 すべてのガード、プレビュー、段階的リリースポリシーは、実際のストアではなく、偽のクライアントと 503 件のテストで検証されています。
• Apple の売上レポートは App Manager キーでは 403 を返します。読み取るには、財務情報へのアクセス権を持つキーが必要です。

全項目の一覧は docs/ROADMAP.md にあります。StorePilot を実アカウントに対して実行した方、特にバイタルをレポートできる規模のアプリをお持ちの方は、これらの項目に関するバグ報告をお寄せいただけると大変役立ちます。

ストアによる厳格な制限事項

これらはここでは修正できません。StorePilot は、回答のように見えるものを返すのではなく、使用時にその旨を伝えます。

• 新しいアプリのレコード作成は、両ストアとも Console でのみ可能です。 Play では最初のアップロードも手動で行う必要があります。
• 各種申告フォームは Console でのみ利用できます — データセーフティ、プライバシーに関する栄養表示、コンテンツレーティング。
• iOS バイナリをアップロードする REST エンドポイントはありません。 asc_upload_build は、実行できるかのように装うのではなく、Transporter/altool の手順を返します。
• Play のレビュー API が返すのは、本番トラックのレビュー、コメント付きのレビュー、そしておおむね直近 7 日分のみです。
• Apple は API を通じた総合評価を一切公開していません。
• Play のレポートデータには 3〜7 日の遅延があり、1 か月分の収益は翌月 5 日ごろに届きます。 それまではレポートは存在せず、StorePilot は 0 ではなく「未公開」と報告します。

クォータ

• Play Developer Reporting：毎秒 10 クエリ。StorePilot は余裕を持たせて毎秒 8 クエリに調整するため、大規模なポートフォリオのスキャンには数秒かかります。
• App Store Connect：キーごとに 1 時間あたり約 3,600 リクエスト。x-rate-limit ヘッダーで報告されます。さらに、文書化されていない 1 分あたりの上限があり、300〜350 件前後で拒否が始まります。クライアントは両方の制限に合わせ、1 分あたり 240 リクエストに抑え、1 時間あたりの残り枠が減るにつれて呼び出し間隔を空けます。
• Apple の salesReports は API の他の機能よりクォータがはるかに少ないため、結果はキャッシュされます。過去の期間は、Apple が再生成することがないため、永久にキャッシュされます。

---

比較

StorePilot は、これらの API を扱う唯一の MCP サーバーではなく、fastlane の代替でもありません。docs/COMPARISON.md では、代替手段を挙げ、それぞれが優れている点と、StorePilot だけが対応する限られた領域を具体的に説明しています。

ドキュメント

• docs/SETUP.md — 認証情報の迷路を最初から最後まで解説します
• docs/TOOLS.md — すべてのツール、引数、制限事項
• docs/COMPARISON.md — 代替手段とファストレーン
• docs/ROADMAP.md — 現状とライブ検証のバックログ
• docs/SECURITY.md — 認証情報の取り扱いと脅威モデル
• CONTRIBUTING.md — セットアップ、基本ルール、実際に役立つこと
• CHANGELOG.md — リリース内容とライブ実行で修正された事項

貢献

最も役立つ貢献は、実際のストアアカウントで StorePilot を実行し、問題が起きた箇所を報告することです。特に、テストアカウントでは Android Vitals にデータが表示されなかったため、データが表示されるほどアプリの規模が大きいアカウントでの報告が役立ちます。CONTRIBUTING.md をご覧ください。

MCP Registry

io.github.sonlenef/storepilot-mcp として公開されています。

mcp-name: io.github.sonlenef/storepilot-mcp

ライセンス

MIT