Mogut

Read-only App Store growth analysis (ASO) MCP server for the Apple ecosystem (iOS + Mac App Store).

Mogut never writes to the App Store. Write actions are handed off as ready-to-run Heimdall tool calls that the user approves.

1.0: 47 tools over 13 live data sources, ending in the report orchestrators. report_app produces the full App Report in one call; the periodic tiers (daily/weekly/monthly) report deltas from local history. See CHANGELOG.md.

Install

npm install -g mogut
mogut setup

The wizard registers Mogut with the MCP clients it finds (Claude Code & Desktop, Codex, Cursor, VS Code, Windsurf, Antigravity) — restart the client once afterwards.

The wizard stores credentials in the macOS Keychain (com.milowda.credentials) with a .env fallback. Secrets are entered in the terminal only — never in chat, never logged, never displayed. See SECURITY.md.

Related MCP server: ASO Score MCP

MCP config

{
  "mcpServers": {
    "mogut": { "command": "mogut", "args": [] }
  }
}

Nine tools are exposed by default: six mogut_* meta tools plus the three report orchestrators (report_app, report_competitor_deep, report_comparison — the fourth, report_actions, lands in v1.1). Everything else is opt-in per profile: set MOGUT_PROFILES="keyword,competitor" (or "all"). mogut_search_tools finds a tool and tells you which profile enables it. The flows are described in GUIDE.md.

What a result looks like

Every tool returns data (structuredContent) plus a writing instruction for the host model — statistics are computed in code, never delegated to the model. Every result carries source, confidence and lastCheckedAt; truncation is visible (fetched/analyzed counts); review and competitor text is marked untrusted data. A broken source becomes a visibly skipped section, never an invented number.

Tiers

mogut_status shows the current tier, verifies credentials live (verify: true) and counts down the 180-day Apple Ads key rotation.

Which App Store Connect role unlocks what

The feed only produces data after that one POST. Mogut never sends it from the MCP surface: run npx mogut analytics enable --app <id> in the terminal (asks for the path to an Admin .p8, uses it in memory, stores nothing), or --print-only to print the request for whoever holds Admin. disable undoes it.

Advanced: Apple Ads popularity index

The official Apple Ads API has no popularity index (verified live: POST /api/v5/keywords/popularities → 404). The number the Ads UI shows comes from an undocumented endpoint that authenticates with a web session, not OAuth. Mogut can read it, but the wizard does not ask for it: it is a pasted browser cookie, it expires, and using it is a grey area against the Apple Ads terms. Without it, keyword_popularity_fetch falls back to a proxy score marked low confidence.

If you want it anyway:

1. Log in at https://app-ads.apple.com and open any campaign screen.

2. Open devtools → Network, filter on /cm/api, click one request.

3. Copy that request's Cookie request header, whole.

4. export MOGUT_APPLE_ADS_SESSION='<the cookie header>' in the environment your MCP client launches Mogut from — or store it under the apple-ads-session account of the com.milowda.credentials Keychain service.

Re-do it when the session expires. mogut_discover_sources shows the source as down once the endpoint starts refusing.

What a report looks like

report_app produces the on-demand full report; daily_digest, weekly_change_report and monthly_status_report produce the periodic tiers, reading deltas from the same local history. Anonymized golden examples of both: EXAMPLE_REPORT_FULL.md · EXAMPLE_REPORT_PERIODIC.md.

Development

npm install && npm run build && npm test

Adding a data source? Read CONTRIBUTING.md — the adapter contract and the fixture requirement are enforced by tests.

src/core/catalog.ts is generated from docs/TOOL_CATALOG.md — regenerate with node scripts/gen-catalog.mjs.

MIT.