MCP Server

Tools

The server exposes 22 tools covering the entire Sonar API — iOS App Store and Google Play, all with one API key: 9 stateless lookups, 7 workspace reads, and 6 write tools that set up your tracking. An agent can create a product, track keywords and competitors, then read back rankings, changes, and gap analyses.

Stateless read tools

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

Workspace read tools (Full plan)

Read your tracked apps, keywords, rankings, and competitor data. Require a Full plan (an active trial counts); the default read-scope key is enough. Available in @sonarapp/mcp ≥ 0.5.0.

Write tools (Full plan + write scope)

Write tools mutate your workspace — they let an agent add your app, link competitors, start rank tracking, annotate keywords, and run competitor scans. They require a Full plan (an active trial counts) and an API key created with the write scope at /developers. Both are enforced server-side.

1. Get an API key

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

The MCP server is published as @sonarapp/mcp on npm and runs via npx — no global install required. Pick your client below.

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 22 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.

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/mcp@0.1.0"]

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