# mrrscope

Query your [MRRscope](https://mrrscope.com) analytics from the terminal — visitors, revenue, MRR, traffic sources, AI crawlers, realtime. Built for AI agents and LLMs 🤖

The CLI is a wrapper around the [public API `/api/v1`](https://mrrscope.com/docs/api-v1): every command maps to a documented REST route, and `--json` prints the raw response.

## Quick start

```bash
npx mrrscope login       # paste an account token (create it in Settings → API)
npx mrrscope sites list
npx mrrscope analytics overview --site my-saas.com --period 30d
```

Or install globally:

```bash
npm install -g mrrscope
```

## Commands

```bash
mrrscope login [--token mrt_xxx]     # token saved to ~/.config/mrrscope/config.json
mrrscope logout

mrrscope sites list

mrrscope analytics overview    --site my-saas.com --period 7d
mrrscope analytics timeseries  --site my-saas.com --from 2026-01-01 --to 2026-01-31
mrrscope analytics pages       --site my-saas.com --limit 25
mrrscope analytics referrers   --site my-saas.com
mrrscope analytics countries   --site my-saas.com
mrrscope analytics devices     --site my-saas.com
mrrscope analytics crawlers    --site my-saas.com   # AI bots, IP-verified
mrrscope analytics realtime    --site my-saas.com

mrrscope tokens list
mrrscope tokens create --name "SEO agent"
mrrscope tokens revoke <id>
```

## For AI agents

```bash
# Compact JSON — pipe into jq, save to a file, feed an agent
MRRSCOPE_TOKEN=mrt_xxx mrrscope --json analytics overview --site my-saas.com | jq '.visitors'
```

Give your agent (Claude Code, Cursor…) an `mrt_` token and it can answer
"how many visitors yesterday?", "which pages earn?", "who is online right now?"
by running the CLI itself.

## MCP server

The package also ships an MCP (Model Context Protocol) server — your agent
discovers 6 read-only analytics tools by itself:

```bash
# Claude Code
claude mcp add mrrscope --env MRRSCOPE_TOKEN=mrt_xxx -- npx -y mrrscope mcp
```

```json
// Claude Desktop / Cursor
{
  "mcpServers": {
    "mrrscope": {
      "command": "npx",
      "args": ["-y", "mrrscope", "mcp"],
      "env": { "MRRSCOPE_TOKEN": "mrt_xxx" }
    }
  }
}
```

Tools: `mrrscope_list_sites`, `mrrscope_overview`, `mrrscope_timeseries`,
`mrrscope_breakdown`, `mrrscope_crawlers`, `mrrscope_realtime`.
MCP guide: https://mrrscope.com/docs/mcp

## Authentication

Two token levels:

- `mrt_` **account token** — full account: every site, plus token management. Create it in [Settings → API](https://app.mrrscope.com/settings?tab=api).
- `wf_` **site key** — read-only analytics, limited to the sites it covers.

Environment overrides: `MRRSCOPE_TOKEN`, `MRRSCOPE_API_BASE`.

## Docs

- CLI guide: https://mrrscope.com/docs/cli
- API reference: https://mrrscope.com/docs/api-v1