Metadata-Version: 2.4
Name: krystalview-mcp
Version: 0.1.1
Summary: KrystalView MCP Server — AI agent access to website analytics, session replay, friction scoring, and anomaly detection.
Project-URL: Homepage, https://krystalview.com
Project-URL: Documentation, https://docs.krystalview.com/integrations/mcp
Project-URL: Repository, https://github.com/McSlaine/krystalview-mcp
Author-email: KrystalView <support@krystalview.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,analytics,krystalview,mcp,session-replay
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Description-Content-Type: text/markdown

# KrystalView MCP Server

Give your AI agents direct access to website analytics. Query visitor sessions, investigate UX friction, analyze conversion funnels, and get anomaly alerts — all from Claude, Cursor, or any MCP-compatible client.

## Quick Start

### Install

```bash
pip install krystalview-mcp
```

### Configure

Generate an API key in your [KrystalView console](https://app.krystalview.com) under **Settings > API Keys**.

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "krystalview": {
      "command": "krystalview-mcp",
      "env": {
        "KRYSTALVIEW_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### Claude Code

```bash
claude mcp add krystalview -- krystalview-mcp
# Then set your API key:
export KRYSTALVIEW_API_KEY="your-api-key-here"
```

#### Cursor

Add to your MCP settings:

```json
{
  "krystalview": {
    "command": "krystalview-mcp",
    "env": {
      "KRYSTALVIEW_API_KEY": "your-api-key-here"
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `get_sessions` | List/search visitor sessions with filters (device, location, friction, rage clicks) |
| `get_session_detail` | Deep dive into a specific session — full timeline, events, navigation path |
| `get_site_stats` | Aggregate performance metrics — sessions, friction, devices, top pages |
| `get_anomalies` | AI-detected anomalies with explanations (traffic spikes/drops, friction surges) |
| `get_funnels` | List defined conversion funnels |
| `get_funnel_analysis` | Step-by-step funnel conversion rates and drop-off analysis |

## Example Prompts

Once connected, try asking your AI assistant:

- *"How's my site performing this week?"*
- *"Show me frustrated mobile users from the last 24 hours"*
- *"Why did our traffic drop yesterday?"*
- *"Where are users dropping off in the checkout funnel?"*
- *"Find sessions with rage clicks on the pricing page"*
- *"Are there any anomalies I should know about?"*

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `KRYSTALVIEW_API_KEY` | Yes | — | Your KrystalView API key |
| `KRYSTALVIEW_BASE_URL` | No | `https://app.krystalview.com/api` | API base URL |
| `KRYSTALVIEW_TIMEOUT` | No | `15` | Request timeout in seconds |

## Rate Limits

API keys have configurable rate limits (default: 60 requests per minute). Rate limit headers are included in every response. If you hit the limit, the server returns a clear error with retry timing.

## Security

- API keys are scoped to a single site — agents can only access data for the site the key was created for
- All requests use HTTPS
- Keys can be rotated or revoked in the KrystalView console
- No data is stored by the MCP server — it proxies directly to the KrystalView API

<!-- mcp-name: io.github.mcslaine/krystalview -->

## License

MIT
