ASO Documentation

Use the local MCP server

AppSprint includes a local MCP server so AI assistants can read your tracked apps, keyword metrics, SDK analytics, App Store Connect pages, Apple Ads campaign structure, ROAS performance, and the structured Apple Ads playbook before proposing guarded changes.

Setup

In the macOS app sidebar, turn on MCP Server. When it is running, the local endpoint is:

http://localhost:9001/mcp

Local to your Mac

Keep AppSprint open while your assistant uses the MCP server. The server runs locally on your Mac and uses the data already available inside the app.

Client configuration

Pick your assistant or editor, add the AppSprint MCP endpoint, then restart or verify the client so the server appears.

Run this command in Terminal.
claude mcp add --transport http app-sprint-aso http://localhost:9001/mcp


claude mcp list
The list command verifies Claude Code can see the server.

Workflow

MCP work is split into three layers so an assistant can collect the right context, explain a plan, and use scoped write tools only when a change is requested.

Read

Inspect tracked apps, rankings, SDK analytics, App Store pages, Apple Ads account state, campaign structure, and ROAS performance.

Plan

Use the structured Apple Ads playbook, safe defaults, formulas, diagnostics, bid rules, and dry-run campaign plans.

Write

Remove tracked keywords, update App Store pages, and apply approved Apple Ads diffs through scoped write tools.

Read analytics

The four analytics tools are read-only. They accept an optional track_id, date range, and force_refresh. Without a track ID, the selected published app is used. Snapshots are shared for 60 seconds so an assistant can combine overview, acquisition, geography, and retention without repeating the same backend request.

  • Date ranges support today, last_3_days, last_7_days, and last_30_days.
  • Source rows can be sorted by installs, trials, purchases, or revenue.
  • Geography can return countries or locations, including coordinates and source mix.
  • Retention rates are returned as fractions, so 0.42 means 42%.

Available tools

Current surface: 38 MCP tools.

ASO and App Store Connect

list_appsList tracked apps with App Store identity context.
get_app_keywordsRead keywords, countries, ranks, notes, and ASO metrics.
search_rankingsRead keyword position history.
add_keywordsAdd tracked keywords for an app and country.
remove_keywordsStop tracking selected keyword IDs for an app.
search_app_storeSearch public App Store results for discovery.
set_keyword_noteSave a note on a tracked keyword.
get_metadata_suggestionsReturn optimization tips per locale.
get_ads_insightsReturn bidding hints from ASO metrics.
get_metadataRead App Store Connect metadata per locale.
update_metadataEdit and save App Store Connect metadata.
get_app_store_pageRead metadata plus screenshot URLs, IDs, display types, and source locales.
upload_app_store_screenshotsPreview or upload local PNG/JPEG screenshots.
delete_app_store_screenshotPreview or delete one editable screenshot by ID.
reorder_app_store_screenshotsPreview or reorder the current editable screenshot set.

Analytics read

get_analytics_overviewRead totals and daily installs, SDK events, trials, and revenue.
get_analytics_sourcesRead acquisition sources with installs, trials, purchases, and revenue.
get_analytics_geographyRead country or city acquisition, revenue, coordinates, and source mix.
get_analytics_retentionRead cohort sizes, retained users, and D1/D7/D30 retention rates.

Apple Ads read

get_apple_ads_connectionCheck connection, org, currency, apps, account status, and guardrails.
list_apple_ads_campaignsList campaigns, ad groups, keywords, statuses, countries, budgets, bids, and match types.
get_apple_ads_performancePull spend, taps, installs/downloads, trials, revenue, ROAS, and impression-share context.
refresh_apple_ads_performanceRefresh Apple Ads ROAS data when the current snapshot is stale.
get_apple_ads_keyword_trendRead daily keyword downloads, trials, spend, revenue, CPI, trial rate, and ROAS.

Apple Ads plan and knowledge

get_apple_ads_playbookReturn setup, bidding, scaling, localization, and decision-tree sections.
get_apple_ads_safe_defaultsReturn Search Results, exact match, Search Match off, and budget guardrails.
diagnose_apple_ads_keywordRecommend raise bid, lower bid, pause, wait, fix screenshots, fix onboarding, or increase budget.
suggest_bid_changesUse ROAS and impression share to return dry-run bid and budget recommendations.
get_apple_ads_formulasReturn TTR, CR, CPI, RPI, ROAS, and break-even CPT formulas.
get_campaign_review_checklistReturn daily, 3-day, weekly, and monthly review cadences.
get_localization_rulesReturn country, language, native-speaker review, and localization rules.
plan_apple_ads_campaignsCreate a dry-run exact-campaign plan with countries, budgets, CPT bids, keywords, Search Match off, and risks.

Apple Ads guarded write

create_apple_ads_campaignsApply an approved campaign plan with confirmation and max budget.
update_apple_ads_bidsBulk update keyword or ad group CPT bids with approval for increases.
update_apple_ads_budgetsChange daily budgets with max-budget and +30% increase guardrails.
pause_apple_ads_entitiesPause campaigns, ad groups, or keywords from an explicit diff or poor ROAS thresholds.
add_apple_ads_keywordsAdd targeting keywords, exact match by default.
add_negative_keywordsAdd exact negative keywords for search-term cleanup.

Write guardrails

  • remove_keywords accepts keyword IDs returned by get_app_keywords. Removal is app-scoped and all-or-nothing, and only stops local tracking.
  • App Store screenshot writes return a dry-run diff and require explicit confirmation before changing App Store Connect.
  • Write tools default to dry runs and return a diff before writing.
  • Live campaign, bid, budget, keyword, negative, and pause changes require explicit confirmation.
  • Budgeted writes require max_daily_budget, and budget increases are blocked unless approved.
  • Campaign plans default to Search Results, one country per campaign, exact match keywords, Search Match off, and iPhone-first planning when that is the optimized experience.
  • ROAS decisions should use spend, taps, installs/downloads, trials, revenue, keyword daily trend, and measurement-readiness context.

Troubleshooting

  • Assistant cannot connect: confirm MCP Server is enabled in the AppSprint sidebar and the app is still open.
  • Tools cannot read App Store Connect metadata: connect App Store Connect first.
  • Analytics tools return no data: select a published tracked app with an active Pro license and confirm that its AppSprint SDK is sending events.
  • Cursor or VS Code does not show the server: save the config file, then restart the editor.