# partnerlens-mcp

MCP server for **Shopify App Store intelligence** — give Claude, Cursor, or any
MCP client access to 17,000+ Shopify apps, 829,000+ reviews, category rankings,
and AI-analyzed review sentiment, powered by the
[PartnerLens](https://www.partnerlens.app) dataset.

Ask things like:

- *"What are merchants complaining about in Klaviyo's 1-star reviews this year?"*
- *"Compare Judge.me, Loox, and Yotpo on rating trend and top pain points."*
- *"Who are the top 10 apps in email-marketing right now?"*
- *"Find underserved pain points in the upsell category I could build an app for."*
- *"Did my uninstalls spike last month, and what are competitors' users complaining about?"* (paid plan)

## Quick start

**1. Get a free API key** — sign up at [partnerlens.app](https://www.partnerlens.app),
then **Settings → API Keys → New Key** (keys look like `as_…`).

**2. Add the server to your client:**

### Claude Code

```bash
claude mcp add partnerlens -e PARTNERLENS_API_KEY=as_your_key -- npx -y partnerlens-mcp
```

### Claude Desktop / Cursor (`mcpServers` JSON)

```json
{
  "mcpServers": {
    "partnerlens": {
      "command": "npx",
      "args": ["-y", "partnerlens-mcp"],
      "env": { "PARTNERLENS_API_KEY": "as_your_key" }
    }
  }
}
```

## Tools

| Tool | What it does |
|---|---|
| `search_apps` | Search apps by name, developer, or slug |
| `get_app` | Full app detail: rating, categories, Built-for-Shopify, latest rank |
| `get_app_reviews` | Individual reviews, newest first, filterable by star rating |
| `get_review_summary` | Rating distribution, sentiment, 12-month velocity, top pain points |
| `compare_apps` | 2–5 apps side by side with review summaries |
| `list_categories` | All App Store categories with app counts |
| `get_top_apps` | Current top-ranked apps in a category |

### Your own data (Unlimited plan)

With a [PartnerLens Unlimited](https://www.partnerlens.app) plan and the
Shopify Partner integration connected (Settings → Integrations), two more
tools unlock your **private** Partner Dashboard data:

| Tool | What it does |
|---|---|
| `get_my_apps` | Your apps synced from your Shopify Partner organization |
| `get_my_metrics` | Your daily installs, uninstalls, active shops, revenue, MRR + movements, churn |

So Claude can answer things like *"did my uninstalls spike after the price
change, and how does my rating trend compare to my top competitor's?"* — your
data and market data in one conversation. Free keys get a clear message
explaining the requirement; the public tools above work for everyone.

## Hosted / HTTP mode

The same binary serves stateless
[Streamable HTTP](https://modelcontextprotocol.io/docs/concepts/transports) for
remote deployment:

```bash
partnerlens-mcp --http --port 3333
# endpoint: http://localhost:3333/mcp
```

In HTTP mode each request's `Authorization: Bearer as_…` header is forwarded to
the PartnerLens API — the server stores nothing and keeps no sessions.

## Environment

| Variable | Purpose |
|---|---|
| `PARTNERLENS_API_KEY` | Required in stdio mode. Free at partnerlens.app |
| `PARTNERLENS_API_URL` | Override API base (default `https://www.partnerlens.app/api/v1`) |
| `PORT` | HTTP port when `--port` isn't passed |

## Rate limits (free tier)

60 requests/minute and 1,000 requests/day per key. Responses carry
`X-RateLimit-*` headers. Need more? [Talk to us](https://www.partnerlens.app).

## Development

```bash
pnpm install
pnpm test        # vitest
pnpm typecheck
pnpm build       # tsup → dist/
```

PRs welcome — tools live in [src/tools.ts](src/tools.ts) as plain data and are
unit-tested without a transport.

## License

MIT