# MCP connector

AppmanAi is listed in [Claude's connector directory](https://claude.ai/directory/appmanai): click
**Connect**, sign in, and Claude gets an ASO analyst with real App Store & Google Play data. Any
other MCP client that supports remote connectors takes one URL. Nothing to install, no API key to
paste — your client authenticates you over OAuth and each call is metered against your credit
balance.

## Add it

One click — Claude opens AppmanAi's directory listing, Cursor and VS Code arrive with the URL
filled in:

<div class="connect-row">
  <a class="connect-primary" href="https://claude.ai/directory/appmanai" target="_blank" rel="noopener">Add to Claude</a>
  <a class="connect-alt" href="cursor://anysphere.cursor-deeplink/mcp/install?name=appmanai&config=eyJ1cmwiOiJodHRwczovL2FwcG1hbmFpLmNvbS9hcGkvbWNwIn0=">Cursor</a>
  <a class="connect-alt" href="vscode:mcp/install?%7B%22name%22%3A%22appmanai%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fappmanai.com%2Fapi%2Fmcp%22%7D">VS Code</a>
</div>

The Cursor and VS Code links hand off to the desktop app over a custom URL scheme — if
that app isn't installed, nothing happens and no error is shown. The
[setup page](https://appmanai.com/mcp-setup) has the config to add by hand.

### Claude

1. Open [AppmanAi in Claude's connector directory](https://claude.ai/directory/appmanai) — or, in
   Claude, **Customize → Connectors → Discover** and search for AppmanAi.
2. Click **Connect**. Claude opens a browser window to AppmanAi. **Sign in or create an account**
   (new accounts confirm their email with a 6-digit code and get free credits, no card) and click
   **Allow**.
3. The `AppmanAi` tools appear in Claude. Ask away.

Prefer to add it by hand? **Customize → Connectors → Add**, choose a custom connector, name it, and
paste the URL — the sign-in is the same:

```
https://appmanai.com/api/mcp
```

### Terminal clients

No deeplink, one line instead — each opens your browser to sign in:

```bash
claude mcp add --transport http appmanai https://appmanai.com/api/mcp
codex mcp add appmanai --url https://appmanai.com/api/mcp
gemini mcp add appmanai https://appmanai.com/api/mcp --transport http
```

### ChatGPT

ChatGPT has no one-click link, and custom MCP connectors sit behind **developer mode** — a
workspace-admin toggle under Permissions & Roles. With it on: **Settings → Connectors → Create**,
paste the URL, choose **OAuth**, and allow access.

That's the whole setup — no runtime to install, no config file, no key handling. Your connection
can be revoked any time: **Disconnect** on your [dashboard](https://appmanai.com/app) cuts it off
immediately, or remove it in Claude's connector settings.

## Tools

Every tool is read-only and covers one endpoint of the [HTTP API](https://appmanai.com/docs/reference/). Cost varies by
endpoint — `list_tools` reports the live price list, and each call reports your remaining balance.
`store` is `android` or `ios`; `country` is a two-letter ISO code (e.g. `US`).

### App Metadata & Search

| Tool | Key inputs | Returns | Credits |
|---|---|---|---|
| `app_metrics_metadata` | `store`, `country`, `package` | Full store listing for one app. | 3 |
| `app_metrics_metadata_batch` | `store`, `country`, `packages[]` | Listings for several apps in one call. | 8 |
| `app_search` | `store`, `country`, `q`, `limit?` | Apps matching a name, with package ids. | 2 |
| `app_similar` | `store`, `country`, `package`, `limit?` | Apps the store considers similar. | 5 |

### App Metrics & Reviews

| Tool | Key inputs | Returns | Credits |
|---|---|---|---|
| `app_metrics_ratings_worldwide` | `store`, `package` | Current rating and star counts in every country. | 6 |
| `app_metrics_ratings_history` | `store`, `country`, `package` | Rating and star breakdown over time. | 5 |
| `app_metrics_installs_history` | `store`, `package`, `from?`, `to?` | Installs worldwide per day; App Store figures are [estimates](https://appmanai.com/docs/guide/installs.md). | 10 |
| `app_metrics_revenue_worldwide` | `store`, `package`, `currency?`, `limit?` | Estimated revenue over the last 30 days, worldwide and by country — an [estimate](https://appmanai.com/docs/guide/revenue.md) on both stores. | 10 |
| `app_reviews` | `store`, `country`, `package`, `star_filter?`, `page?` | Real user reviews. | 4 |

### App Category Ranking & Top Charts

| Tool | Key inputs | Returns | Credits |
|---|---|---|---|
| `app_category_rankings` | `store`, `country`, `package`, `category?`, `sub_category?` | Every chart the app appears in, with its rank. | 3 |
| `app_category_rankings_single` | `store`, `country`, `package`, `category?`, `sub_category?` | The app's position in one named chart. | 2 |
| `app_category_rankings_history` | `store`, `country`, `package`, `category` | The app's chart position over time. | 6 |
| `app_category_start_rankings` | `store`, `country`, `packages[]` (`package:min_date`, date required) | Where each app entered a chart. | 5 |
| `category_top_apps` | `store`, `country`, `category?`, `sub_category?`, `limit?` | The apps at the top of a category chart. | 5 |

### Keyword Metrics, Search & Suggestions

| Tool | Key inputs | Returns | Credits |
|---|---|---|---|
| `keyword_metrics` | `store`, `country`, `keyword` | SAP (popularity), difficulty, languages. | 4 |
| `keyword_metrics_sap` | `country`, `keyword` | Just the popularity score for one keyword. | 4 |
| `keyword_metrics_sap_batch` | `country`, `keywords[]` | Popularity scores for a list of keywords. | 9 |
| `keyword_metrics_volatility` | `store`, `country`, `from?`, `to?` | How much rankings moved in one country over a range. | 8 |
| `keyword_metrics_volatility_worldwide` | `store`, `date?`, `window?` | Ranking volatility per country on one date. | 12 |
| `keyword_top_apps` | `store`, `country`, `keyword`, `limit?` | The apps ranking highest for a keyword. | 5 |
| `keyword_suggestions` | `store`, `country`, `keyword`, `limit?` | Related keyword suggestions from a seed. | 5 |
| `keyword_suggestions_worldwide` | `keyword`, `limit?` | Suggestions with SAP across all markets, no store/country. | 10 |

### Keyword data by app

| Tool | Key inputs | Returns | Credits |
|---|---|---|---|
| `keyword_app_metrics_rankings` | `store`, `country`, `package`, `keyword` | The app's current rank for that keyword. | 2 |
| `keyword_app_metrics_rankings_batch` | `store`, `country`, `package`, `keywords[]` | One app's rank across many keywords in one call. | 9 |
| `keyword_app_metrics_rankings_history` | `store`, `country`, `package`, `keyword`, `period?` | The app's rank over time (dated series). | 6 |
| `keyword_app_metrics_rankings_worldwide` | `store`, `package`, `keyword` | One app's rank for one keyword in every country. | 12 |
| `keyword_app_suggestions` | `store`, `country`, `package`, `limit?` | The keywords an app ranks for. | 6 |
| `keyword_app_competitors` | `store`, `country`, `package`, `limit?` | Keywords the app's competitors rank for. | 6 |
| `keyword_app_overlap` | `store`, `country`, `packages[]`, `min_rank?`, `min_sap?`, `min_apps?` | Keywords a set of apps compete on, with each app's rank. | 7 |

### Generation

| Tool | Key inputs | Returns | Credits |
|---|---|---|---|
| `generate_keywords` | `store`, `country`, `package`, `language?` | Keyword ideas from the app's own listing, scored. | 12 |
| `generate_app_metadata` | `store`, `country`, `description`, `title?`, `category_tag?`, `keywords[]?` | Rewritten listing copy — title, short and long description. | 15 |

### Reference & account

| Tool | Key inputs | Returns | Credits |
|---|---|---|---|
| `list_countries` | `store?`, `country?`, `language?` | Supported countries + per-store coverage. | free |
| `list_categories` | `store` | The store's category tree and chart tags. | free |
| `list_features` | `store?`, `country?` | Which parts of the dataset exist for a market. | free |
| `user_balance` | — | Your credit balance and what it is worth. | free |
| `user_api_usage` | `days?` | Credits spent and requests made, per route. | free |
| `list_tools` | — | This catalogue with live prices and your balance. | free |

Tool responses carry the API's JSON (`{ status, meta, data }`); the useful payload is under
`data`. Remaining credits are reported with each successful call.

## Example prompts

- "What keywords does the Discord app rank for on Google Play?"
- "Profile the keyword 'habit tracker' on the US App Store."
- "Which apps rank top-10 for 'voice chat' on the US App Store?"

## Errors

Errors surface with the platform's unified codes, and every failed tool call tells the agent
what to do next: fix the arguments, wait before retrying (`RATE_LIMIT_EXCEEDED` names the
seconds), retry once on our own faults, or stop — `INSUFFICIENT_CREDITS` is a hard stop until
credits are added. See [Errors & request_id](https://appmanai.com/docs/guide/errors.md) for the full list.

## Credits & billing

Each tool call debits that endpoint's credit cost from your balance — the same balance, prices and
metering the HTTP API uses. Ask for `list_tools` to see the current price list, or `user_balance`
for what is left.

Your balance has up to three parts. Your plan's **monthly credits** refresh on your own signup date
(or subscription date on Base) and do not roll over; **bonus credits**, like the signup bonus,
expire on the date `user_balance` shows; **credit packs** never expire. Whatever expires soonest
is spent first, so nothing is wasted. Manage your
plan from your [dashboard](https://appmanai.com/app).

## Prefer the HTTP API?

For scripts, CI, and back-end integrations, skip the connector: create a Bearer key in your
[dashboard](https://appmanai.com/app) and call the [HTTP API](https://appmanai.com/docs/guide/quickstart.md) directly. Same data, same credits, no OAuth.