# OxiLytics MCP server

A read-only [Model Context Protocol](https://modelcontextprotocol.io) server for
[OxiLytics](https://oxisoft.io), self-hosted app analytics for the App Store and
Google Play.

It lets an AI assistant answer questions about your apps — downloads, crashes,
reviews, sync health — by talking to your own OxiLytics instance. Your data stays
on your server.

## Read-only by design

OxiLytics API tokens are read-only, enforced on the server: any non-GET request
made with a token is rejected with `403 read_only_token`. This MCP server can
read your analytics and nothing else. It cannot change settings, edit products,
trigger syncs or touch users — not because it politely declines, but because the
server refuses.

## Requirements

- An OxiLytics instance (self-hosted)
- A read-only API token: **My profile → API tokens → Create**
- Python 3.10+

## Install

```bash
uv tool install oxilytics-mcp
```

Or from source:

```bash
git clone https://github.com/oxisoft/oxilytics-mcp
cd oxilytics-mcp
uv pip install -e .
```

## Configure

The server reads two environment variables:

| Variable | Meaning |
|---|---|
| `OXILYTICS_SERVER_URL` | Base URL of your instance, e.g. `https://analytics.example.com` |
| `OXILYTICS_TOKEN` | Your read-only API token |
| `OXILYTICS_ENV_FILE` | Optional: path to a file containing the two above, if you prefer not to put a token in your client config |

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "oxilytics": {
      "command": "uvx",
      "args": ["oxilytics-mcp"],
      "env": {
        "OXILYTICS_SERVER_URL": "https://analytics.example.com",
        "OXILYTICS_TOKEN": "oxi_your_token_here"
      }
    }
  }
}
```

If you would rather keep the token out of the config file, drop it in a
`chmod 600` file as `OXILYTICS_TOKEN=...` and set `OXILYTICS_ENV_FILE` to that
path instead.

## Tools

| Tool | What it answers |
|---|---|
| `overview` | Start here. Stores configured, app and product counts, totals, recent sync outcomes. |
| `list_apps` | Store listings with ids, platform, rating, last sync. Filter by name or show unassigned. |
| `list_products` | Products with download and crash totals. |
| `metrics` | Totals for a metric over a range, compared to the preceding period. |
| `timeseries` | A metric over time, by day, week or month. |
| `top_countries` | Ranked countries for a metric. |
| `reviews` | User reviews, filterable by rating, country and free text. |
| `sync_runs` | Recent sync runs with status and row counts. |
| `sync_run_log` | One run's log, grouped by default, full lines on request. |

Metrics: `downloads`, `redownloads`, `updates`, `uninstalls`, `crashes`, `anrs`,
`active_devices`.

## Zero is not always zero

When a store has not delivered data yet, the honest answer is "no data", not
"zero downloads". Those look identical in a number and mean very different
things. Where every value comes back zero, these tools say so and point you at
`sync_run_log` rather than letting you conclude your app has no users.

## Example questions

- "How are my apps doing this month?"
- "Which countries download Sudoku the most?"
- "Show me every one-star review mentioning crashes."
- "Did the last sync actually work?"

## License

MIT