mcp-analytics

# MCP Analytics Suite

**The statistical analyst in your AI chat.** Bring a CSV (or connect a live source) and a question. A standing team of specialist agents builds a custom analysis specific to your data, validates the methodology, and ships back a citable, interactive report. The analysis is **yours** — it lives in your library, reruns on fresh data for a fraction of the creation cost, and is queryable from Claude, Cursor, or any MCP client. The work compounds.

> **This is the public listing and documentation repository.** Issues, feature requests, and examples live here. The API server code is maintained separately.

[Sample Reports →](https://mcpanalytics.ai/sample-reports.html) • [Try Demo →](https://mcpanalytics.ai/demo.html) • [Pricing →](https://mcpanalytics.ai/pricing.html)

<div align="center">

[![Glama Score](https://glama.ai/mcp/servers/embeddedlayers/mcp-analytics/badges/score.svg)](https://glama.ai/mcp/servers/embeddedlayers/mcp-analytics)
[![npm](https://img.shields.io/npm/v/@mcp-analytics/mcp-analytics)](https://www.npmjs.com/package/@mcp-analytics/mcp-analytics)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-MCP_Compatible-blue)](https://mcpanalytics.ai/install)
[![Docs](https://img.shields.io/badge/Docs-mcpanalytics.ai-brightgreen)](https://mcpanalytics.ai/docs)

**Hire the team. Own the analysis. Rerun forever.**

[🚀 Quick Start](#quick-start) • [🔄 How It Works](#how-it-works) • [🛠️ MCP Tools](#mcp-tools) • [🛡️ Security](#security--compliance) • [📖 Documentation](#documentation)

</div>

<div align="center">

[![Demo Video](assets/demo-preview.png)](https://github.com/embeddedlayers/mcp-analytics/releases/download/v1.0.4/demo.mp4)

*Click to watch: Ask a question → upload data → get an interactive report with AI insights*

</div>

---

## Overview

You bring data and a question. A pipeline of specialist agents — spec drafter, builder, verifier, fixer, deployer — turns your question into a custom analysis for your data. The result is an interactive report: charts, AI-narrated insights, exportable PDF, embedded source code, citable. Every commissioned analysis joins your private library — query it from any MCP client, rerun on fresh data with one call, share with collaborators on your terms.

**Cornerstone modules** ship pre-built (t-tests, regression, churn, segmentation, forecasting, customer LTV, A/B testing, time series, survival analysis, and more) so you can see a finished report in under a minute and verify the team can build things that work. **Custom analysis creation** is the named revenue event — pay once to build the capability, own it, rerun for a fraction of the creation price. A build that fails is never billed.

Connect data however it lives: CSV upload, public URL, or live OAuth connectors for Google Analytics 4 and Google Search Console (more coming). Once a connector is linked, every rerun pulls fresh data automatically — no re-export step.

### Choose Your Depth — Four Tiers

Every analysis runs through the same validated pipeline — you choose how far it goes:

| Tier | What you get | Time |
|------|-------------|------|
| **Snapshot** | One chart and a verified insight — an instant read of your data, covered by your welcome credits | ~2 min |
| **JSON** | One computed statistical answer — the numbers and the method — deployed as a tool you re-run on fresh data | ~5 min |
| **Brief** | The computed answer, presented — chart, key figures, and method on a single shareable page | ~7 min |
| **Deck** | The full study — a complete statistical report built to your brief and independently verified; a durable module you own and re-run forever | 30–45 min |

More rigor outranks more charts: going deeper buys real statistical methods — hypothesis tests, regression, diagnostics — not just more cards. You pay for depth, and only if the build succeeds. [How the tiers work →](https://mcpanalytics.ai/tiers.html)

### Why MCP Analytics

- **Citable** — APA / MLA / Chicago / BibTeX in one click, ready for papers, decks, and regulatory filings
- **Sourceable** — R source code embedded in every report; a skeptical reader can run it and get the same answer
- **Reproducible** — fixed seeds, Docker isolation, validated methods; same input → same output, forever
- **Yours** — every commissioned module is private to your account; rerun on fresh data, query across your portfolio
- **MCP-native** — query the library from Claude, Cursor, Windsurf, or any MCP client
- **Secure** — OAuth2, encryption at rest, isolated container processing per analysis
- **Honest** — when an analysis has issues, the team gives you a free re-run; the relationship is built on the report being right

## Quick Start

### 1. Get an API Key

Sign up free at [account.mcpanalytics.ai](https://account.mcpanalytics.ai), go to account settings, and copy your API key (starts with `mcp_`). You get **500 welcome credits** — no credit card required. That covers a one-page Brief, or a couple of instant Snapshots.

### 2. Connect

Three options — all connect to the same platform with the same tools.

#### Option A: npx Install (Recommended)

Works with Claude Desktop, Cursor, Windsurf, and any stdio MCP client. Requires Node.js 18+.

**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "mcpanalytics": {
      "command": "npx",
      "args": ["-y", "@mcp-analytics/mcp-analytics"],
      "env": {
        "MCP_ANALYTICS_API_KEY": "mcp_your_key_here"
      }
    }
  }
}
```

**Cursor / Windsurf** — add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mcpanalytics": {
      "command": "npx",
      "args": ["-y", "@mcp-analytics/mcp-analytics"],
      "env": {
        "MCP_ANALYTICS_API_KEY": "mcp_your_key_here"
      }
    }
  }
}
```

**Claude Code** — run in your terminal:

```bash
claude mcp add mcpanalytics -- npx -y @mcp-analytics/mcp-analytics
# Then set MCP_ANALYTICS_API_KEY in your environment
```

#### Option B: Direct API Key (No npm)

For MCP clients that support Streamable HTTP transport with custom headers:

```json
{
  "mcpServers": {
    "mcpanalytics": {
      "url": "https://api.mcpanalytics.ai/mcp/api-key",
      "headers": {
        "X-API-Key": "mcp_your_key_here"
      }
    }
  }
}
```

#### Option C: OAuth2 (No API Key)

Zero-config — a browser opens for login on first connection:

```json
{
  "mcpServers": {
    "mcpanalytics": {
      "url": "https://api.mcpanalytics.ai/auth0"
    }
  }
}
```

#### Browse Tools First (No Account Needed)

Explore the full tool catalog before signing up:

```bash
# Static metadata (tool names, descriptions, all transport options)
curl https://api.mcpanalytics.ai/.well-known/mcp.json

# MCP protocol discovery (no auth — works with any MCP client)
curl -X POST https://api.mcpanalytics.ai/mcp/discover \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{}}'
```

### 3. Start Analyzing

Restart your MCP client. Ask:

- *"Upload sales.csv and find what drives revenue"*
- *"What statistical test should I use for this survey data?"*
- *"Forecast next quarter's sales from this time series"*

## How It Works

### The MCP Analytics Workflow

1. **Upload your data** — `datasets_upload` securely processes your CSV (or reuse an existing dataset / connected source)
2. **Commission the analysis** — `create_analysis` takes your question in plain language, your dataset, and the tier you choose (snapshot, json, brief, or deck)
3. **Watch it build** — `build_status` reports progress, queue position, and the report link when done
4. **Get the report** — `reports_view` delivers the interactive report; `report_cards` displays individual cards inline
5. **Rerun forever** — `run_analysis` re-runs any analysis you own on fresh data for a fraction of the creation cost

```
User: "What drives our sales growth?"
MCP Analytics:
  → Scopes the right statistical method for your data's shape
  → Writes validated R in an isolated container — deterministic, fixed seeds
  → Runs it, then independently verifies numbers and narrative
  → Returns a citable, interactive report you own
```

## MCP Tools

The platform provides a complete suite of MCP tools for end-to-end analytics:

### Analysis
- **`create_analysis`** - Commission a new analysis from a plain-language question, at the tier you choose
- **`build_status`** - Track a build: stage progress, queue position, report link
- **`run_analysis`** - Run an analysis you own (or one discovered via `discover_tools`) on fresh data
- **`modify_analysis`** - Turn an existing analysis into a new version — reword the question, change the framing

### Discovery
- **`discover_tools`** - Browse what you can run: your commissioned analyses plus the prebuilt library
- **`tools_schema`** - Get an analysis's parameter schema — always call this before `run_analysis`

### Data Management
- **`datasets_upload`** - Secure data upload with encryption
- **`datasets_list`** - List and search your uploaded datasets

### Connectors
- **`connectors_list`** - List available data source connections
- **`connectors_query`** - Pull live data from a connected source

### Reporting & Insights
- **`reports_view`** - Get a shareable browser link for a report
- **`reports_list`** - Your report library — every analysis delivered, searchable in plain language
- **`report_cards`** - Browse a delivered report's individual cards (charts, tables, insights)
- **`ask_library`** - Ask one question across *all* your delivered analyses; get a synthesized answer with citations back to each source report
- **`agent_advisor`** - AI help desk — which analysis fits your question, and how to read the result

### Platform Tools
- **`billing`** - Usage and credit management
- **`account_link`** - Link to the right account page for anything not