# AppNiche MCP Server

Open-source Model Context Protocol server for iOS App Store market research with
[AppNiche](https://getappniche.com/). It gives Claude, Cursor, Codex, and other MCP clients four
read-only tools for app discovery, directional revenue and download estimates, ASO keyword
research, and review analysis.

This repository runs a local stdio bridge to the AppNiche REST API. AppNiche also provides a
[hosted Streamable HTTP MCP endpoint](https://getappniche.com/docs/mcp-setup) if your client
supports remote servers directly.

## Tools

| Tool | What it does | Credits |
| --- | --- | ---: |
| `search_apps` | Search and filter iOS apps by keyword, category, rating, reviews, downloads, revenue, and sort order. | 1 |
| `get_app_detail` | Get metadata, ratings, and directional revenue and download estimates for one app. | 1 |
| `get_keyword_difficulty` | Score one iOS App Store keyword for difficulty and opportunity. | 10 |
| `get_app_reviews` | Fetch enriched review rows with sentiment and topic signals. | 1 |

All tools are read-only and marked with MCP read-only annotations.

## Requirements

- Node.js 18 or newer.
- An AppNiche API key from
  [Settings > API Keys](https://app.getappniche.com/settings/api-keys).

API and MCP access use the same credit pool. Current limits, pricing, and error behavior are
documented in the [API quickstart](https://getappniche.com/docs/api-quickstart). Never commit an
API key to source control.

## Quick start

Run directly from GitHub with `npx`:

```json
{
  "mcpServers": {
    "appniche": {
      "command": "npx",
      "args": ["-y", "github:skiffer/appniche-mcp-server"],
      "env": {
        "APPNICHE_API_KEY": "getappniche_replace_me"
      }
    }
  }
}
```

Or clone and build locally:

```bash
git clone https://github.com/skiffer/appniche-mcp-server.git
cd appniche-mcp-server
npm ci
npm run build
APPNICHE_API_KEY=getappniche_replace_me node dist/index.js
```

For a local clone, point your MCP client to `node` with the absolute path to `dist/index.js` and
set `APPNICHE_API_KEY` in the server environment.

Docker is also supported:

```bash
docker build -t appniche-mcp-server .
docker run --rm -i \
  -e APPNICHE_API_KEY=getappniche_replace_me \
  appniche-mcp-server
```

Keep stdin open with `-i`; stdio carries the MCP JSON-RPC connection.

## Hosted MCP alternative

Clients that support Streamable HTTP can use the hosted server without installing this bridge:

```text
URL: https://api.getappniche.com/mcp
Authorization: Bearer YOUR_API_KEY
```

Exact setup snippets for Claude Code, Claude Desktop, Cursor, and generic MCP clients are in the
[AppNiche MCP setup guide](https://getappniche.com/docs/mcp-setup).

## Development

```bash
npm install
npm test
```

`npm test` compiles the TypeScript project, tests API request and error behavior, starts the
server over stdio, and verifies the published tool list. CI also builds the production Docker
image.

## Data caveats

Revenue and download values are modeled estimates derived from public App Store signals. Treat
them as directional market intelligence, not accounting data. AppNiche currently covers the
Apple App Store; this server does not claim Google Play coverage.

## License

MIT