Sonar MCP Server

Tools

The server exposes 80 tools covering the entire Sonar API — iOS App Store and Google Play, all with one API key: 10 stateless lookups, 19 workspace reads (including App Store Connect sales and engagement and your review inbox), 22 write tools that set up and manage your tracking, alerts and review replies, 12 Screenshot Studio tools, and 17 Ad Spy tools for your competitors' Meta ads and TikTok videos. The hosted endpoint exposes 79 tools; filesystem screenshot export is available only in the local package. An agent can create a product, track keywords and competitors, then read back rankings, changes, discovered-keyword suggestions, review insights, and gap analyses — and tear any of it down again.

Stateless read tools

Live store lookups — no tracking required. Work on any plan with credits.

When the store is throttling, sonar_app_lookup, sonar_app_search, sonar_app_reviews and sonar_keyword_suggestions can return Sonar's stored copy instead of an error. The result is then { data, meta }, with meta.stale: true, the copy's date in meta.stale_as_of, and a meta.note for the agent to pass on.

Compact by default. sonar_app_search, sonar_top_charts, sonar_get_app, sonar_app_rankings, sonar_keyword_rankings, sonar_discovered_keywords, sonar_ad_spy_ads and sonar_ad_spy_tiktok_posts take fields: "compact" | "full" and default to compact, which leaves out long descriptions, screenshot and icon URLs, per-day grids and internal ids. A 50-keyword rank history drops from about 38k to about 5.6k tokens. Pass fields: "full" when the agent needs the rest.

Workspace read tools (Indie or Agency plan)

Read your tracked apps, keywords, rankings, competitor data, products, alert subscriptions, and your own iOS apps' App Store reviews (the review tools also need App Store Connect connected in Sonar). Require an Indie or Agency plan (an active trial counts); the default read-scope key is enough. Available in @sonarapp/mcp ≥ 0.5.0.

Write tools (Indie or Agency plan + write scope)

Write tools mutate your workspace — they let an agent add your app, link competitors, start rank tracking, annotate keywords, run competitor scans, manage alert subscriptions, reply to your App Store reviews, and untrack or delete anything it set up. sonar_post_review_reply publishes a public reply under your developer name and needs an Admin-role App Store Connect key. They require an Indie or Agency plan (an active trial counts) and either an OAuth sign-in on the hosted endpoint (which carries write access — the grantor is the account owner) or an API key created with the write scope at /developers. Both are enforced server-side.

Screenshot Studio tools (Indie or Agency plan; mutations need write scope)

Agents author app-store screenshot sets as layout JSON; humans review and fine-tune the same sets in the Screenshot Studio (every set response carries a studio_url). Call sonar_screenshot_layout_guide once before authoring layouts. Image fields accept https:// URLs — fetched and inlined server-side.

Ad Spy tools (Indie or Agency plan; lookups and changes need write scope)

Your competitors' Meta ads and public TikTok videos. Start with sonar_ad_spy_competitors. Cached reads are free; searches, refreshes of a copy over 24 hours old, an ad's first analysis and scripts spend the account's daily Ad Spy lookups (10 on a trial, 25 on Indie, 100 on Agency, shared with the dashboard). Past them a refresh returns the cached copy with a meta.note to relay. Scans never link a page on their own: the agent shows the candidates and links the one the user picks.

1. Get an API key (or skip this step entirely)

Using an OAuth-capable client? Claude Code, Claude (Desktop and claude.ai custom connectors), Cursor and Codex can use the hosted endpoint with no API key at all — the first tool call that needs your account opens a browser sign-in, you approve it with your Sonar login, and the agent gets full access (read + write) to the workspace you own. API keys below are for the npx package, scripts, and clients without OAuth support. Per-client setup: Connect your agent.

No key? The server runs in free mode: app lookup, app search, ASO score, keyword extraction, keyword suggestions and top charts work with no key at all (shared 30 requests/day per IP), and keyword metrics allows 5 keywords/day. Just skip the env block in the config below and ask your agent about ASO. For everything else, you need a Sonar API key. Get one at trysonar.app/developers — keys start with aso_.

New accounts receive 50 free credits on signup — enough to evaluate every endpoint. Top up with prepaid packs from $10 (1,000 credits) when you need more. No subscription required; see the credits page for details and pack sizes.

2. Add the server to your MCP client

Two ways to connect: the hosted endpoint (nothing to install) or the @sonarapp/mcp npm package run locally via npx. Pick whichever your client supports — the tools are identical.

Hosted endpoint (no install)

In ChatGPT, use the Sonar app — there's no URL to add (see ChatGPT below). It runs on https://trysonar.app/mcp/chatgpt.

For Claude and other streamable-HTTP MCP clients, use https://trysonar.app/mcp. OAuth-capable clients (Claude Code, Claude Desktop and claude.ai custom connectors, Cursor, Codex) need no API key at all — add the server and a browser window asks you to authorize with your Sonar login the first time a tool needs it. Cursor takes { "mcpServers": { "sonar": { "url": "https://trysonar.app/mcp" } } } in ~/.cursor/mcp.json; Codex takes url = "https://trysonar.app/mcp" under [mcp_servers.sonar] in ~/.codex/config.toml, then codex mcp login sonar. Claude Code:

claude mcp add --transport http sonar https://trysonar.app/mcp

Alternatively, pass an API key as a bearer token — required for clients without OAuth support:

claude mcp add --transport http sonar https://trysonar.app/mcp --header "Authorization: Bearer aso_your_key_here"

Or as a remote-server config block:

{
  "mcpServers": {
    "sonar": {
      "url": "https://trysonar.app/mcp",
      "headers": { "Authorization": "Bearer aso_your_key_here" }
    }
  }
}

Claude Desktop

Open the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the sonar entry:

{
  "mcpServers": {
    "sonar": {
      "command": "npx",
      "args": ["-y", "@sonarapp/mcp"],
      "env": {
        "SONAR_API_KEY": "aso_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The 80 sonar_* tools will appear in the tool picker.

Claude Code

One-liner from your shell:

claude mcp add sonar -e SONAR_API_KEY=aso_your_key_here -- npx -y @sonarapp/mcp

Restart your Claude Code session and the tools will load automatically.

Cursor

Add to ~/.cursor/mcp.json (or per-project .cursor/mcp.json):

{
  "mcpServers": {
    "sonar": {
      "command": "npx",
      "args": ["-y", "@sonarapp/mcp"],
      "env": { "SONAR_API_KEY": "aso_your_key_here" }
    }
  }
}

Codex CLI

One-liner (recent Codex versions):

codex mcp add sonar --env SONAR_API_KEY=aso_your_key_here -- npx -y @sonarapp/mcp

Or add the server manually to ~/.codex/config.toml:

[mcp_servers.sonar]
command = "npx"
args = ["-y", "@sonarapp/mcp"]
env = { "SONAR_API_KEY" = "aso_your_key_here" }

Start a new Codex session and the sonar_* tools will be available.

ChatGPT

Sonar is a published app in ChatGPT, so there's no server URL, config file or API key to add:

• Open the Sonar app in ChatGPT.
• Connect it to your ChatGPT account.
• Sign in with your Sonar account when ChatGPT asks. Approving the connection grants read and write access to the workspace you own, subject to your account's permissions and entitlements. If a session expires, reconnect when prompted.

Before you sign in, the free research tools (app lookup, app search, ASO score, keyword extraction, keyword suggestions, keyword metrics and top charts) already work within the keyless daily limits. The app talks to https://trysonar.app/mcp/chatgpt, the ChatGPT version of the hosted endpoint with the same 79 tools. Step-by-step guide: Connect Sonar to ChatGPT.

Cline / other MCP clients

Most clients use the same command + args + env shape. Point the command at npx -y @sonarapp/mcp and pass SONAR_API_KEY in the env. Some clients require an absolute path to npx — run which npx and use that.

3. Try it

Once installed, try prompts like:

• “Use Sonar to look up Spotify on iOS in the US store and report its rating, review count, and category.”
• “Run an ASO audit on com.duolingo on Android and tell me what to fix.”
• “Research the keyword habit tracker on iOS — give me difficulty, popularity, and 5 related terms with lower difficulty I should consider.”
• “Pull the 50 most recent 1- and 2-star reviews of 1517783697 on iOS US and group complaints by theme.”
• “Search meditation on the App Store and estimate monthly revenue for the top 5 results.”
• “Create a Sonar product for my app com.example.myapp, track its top 20 extracted keywords, and add Headspace as a competitor.”
• “How did my tracked keywords move in the last 30 days? Flag anything that dropped more than 5 spots and check whether a competitor shipped a release around that time.”

Configuration

Pinning a version

By default npx -y @sonarapp/mcp resolves to the latest version. To pin:

"args": ["-y", "@sonarapp/[email protected]"]

See the package on npm for the version history.

Privacy & data flow

The MCP server is a thin client around the Sonar REST API. Your API key is sent as a Bearer token over HTTPS. Tool inputs and the resulting JSON pass through your AI client; the @sonarapp/mcp package itself does not log anything.

Troubleshooting

“SONAR_API_KEY is not set”

Your MCP client did not pass the env var through. Check the env section of your client's config. Some clients ignore env when the command path isn't absolute — try which npx and use that path.

“Authentication failed”

Your key is invalid, expired, or your subscription lapsed. Check /developers.

Tools don't appear in the picker

Restart the MCP client after editing config. In Claude Desktop, fully quit (Cmd+Q) — closing the window isn't enough. In Claude Code, end the session and start a new one.

See also

• REST API reference — same data, called over HTTP
• CLI reference — same data, from your terminal
• API Credits — pricing for AI agents
• @sonarapp/mcp on npm
• Source on GitHub
• Agent skills on GitHub — ready-made ASO workflows (keyword research, audits, competitor analysis) for Claude Code, Cursor, and any Agent Skills-compatible client