# 🔍 aso-mcp

**Free App Store keyword research for your AI.** No API keys. No signup. No subscription.

Plug it into Claude, Cursor, Windsurf, or any MCP client and research App Store keywords conversationally.

[![PyPI](https://img.shields.io/pypi/v/aso-mcp?color=blue)](https://pypi.org/project/aso-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

---

## Install in 10 seconds

### Claude Code
```bash
claude mcp add aso -- uvx aso-mcp
```

### Claude Desktop
Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "aso": {
      "command": "uvx",
      "args": ["aso-mcp"]
    }
  }
}
```

### Cursor / Windsurf
Add to your MCP settings:
```json
{
  "mcpServers": {
    "aso": {
      "command": "uvx",
      "args": ["aso-mcp"]
    }
  }
}
```

That's it. No API keys. No environment variables. Just works.

---

## What can it do?

Once installed, just talk to your AI naturally:

> *"Research the keyword 'habit tracker' in the US App Store"*

> *"Compare these keywords and rank them by opportunity: cable identifier, wire color code, voltage calculator, circuit breaker finder"*

> *"Find me keywords with popularity above 30 and difficulty below 40 from this list: ..."*

> *"Show me who's ranking for 'meditation app' and how hard it is to compete"*

> *"Suggest optimized metadata for my app CableID targeting cable identification keywords"*

> *"Scan 'budget planner' across the US, UK, Germany, Japan and Brazil stores"*

---

## Tools

| Tool | What it does |
|------|-------------|
| `aso_research_keyword` | Full analysis — popularity, difficulty, opportunity score, download estimates, top competitors |
| `aso_batch_research` | Research up to 20 keywords at once, ranked by opportunity |
| `aso_competitor_analysis` | Deep dive into who's ranking — ratings, reviews, pricing, developer, app age |
| `aso_find_opportunities` | Scan up to 30 keywords, filter by your thresholds, return only the good ones |
| `aso_suggest_metadata` | Generate optimized title, subtitle, and keyword field backed by real data |
| `aso_country_scan` | Check a keyword across up to 15 App Store regions |

---

## How scoring works

All data comes from Apple's free **iTunes Search API**. No paid APIs, no scraping, no Apple Search Ads account needed.

### Popularity (1–100)

A 6-signal model estimating how often a keyword is searched:

| Signal | Points | What it measures |
|--------|--------|-----------------|
| Result count | 0–25 | How many apps appear for this keyword |
| Leader strength | 0–30 | Rating volume of top-ranking apps |
| Title match density | 0–20 | How many apps use this keyword in their title |
| Market depth | 0–10 | Whether strong apps appear deep in results |
| Specificity penalty | −30 to 0 | Adjusts for generic terms that inflate counts |
| Exact phrase bonus | 0–15 | Rewards multi-word keywords with precise matches |

### Difficulty (1–100)

A 7-factor weighted model estimating how hard it is to rank:

| Factor | Weight | What it measures |
|--------|--------|-----------------|
| Rating volume | 30% | How many ratings competitors have |
| Dominant players | 20% | Whether apps with 100K+ ratings dominate |
| Rating quality | 10% | Average star ratings |
| Market maturity | 10% | How long competitors have been listed |
| Publisher diversity | 10% | Few publishers vs many |
| App count | 10% | Total number of results |
| Content relevance | 10% | How well results actually match the keyword |

### Opportunity labels

| Label | Meaning |
|-------|---------|
| **Sweet Spot** | High popularity + low difficulty — go build this |
| **Hidden Gem** | Decent popularity + very low difficulty |
| **Competitive Opportunity** | High popularity, moderate difficulty — needs a strong USP |
| **Worth Investigating** | Promising but do more research |
| **Low Volume** | Easy to rank but few people searching |
| **Avoid** | Too competitive for the search volume |

### Download estimates

3-stage pipeline per ranking position: popularity → estimated daily searches → tap-through rate (power-law decay) → install conversion (35–55% for free apps).

---

## Rate limits

The iTunes Search API is free but rate-limited. The client enforces a 3-second minimum between requests. Batch operations take roughly `n × 3` seconds.

---

## FAQ

**How accurate is this compared to paid tools like Astro or AppTweak?**

Paid tools have access to Apple Search Ads impression data across thousands of advertisers, giving them more precise volume estimates. This tool uses publicly available iTunes Search API data with a multi-signal scoring model. It's very good for *relative* comparisons (keyword A vs keyword B) and identifying opportunities. It won't give you the exact daily search volume that a $100/month tool would.

**Do I need an Apple developer account?**

No. The iTunes Search API is completely public.

**Does this work for Google Play?**

Not yet. The iTunes Search API only covers the Apple App Store. Google Play support would require a different data source.

**Can I use this for commercial research?**

Yes. MIT licensed. Do whatever you want with it.

---

## Contributing

PRs welcome. If you want to improve the scoring model, add new tools, or support new data sources, open an issue first so we can discuss the approach.

---

## License

MIT — free to use, modify, and distribute.

---

**Built by [@heyb3n_](https://x.com/heyb3n_)** — electrician turned iOS dev, building AI tools for indie developers.
