Clarity MCP Server — Remote Setup Guide

A Model Context Protocol (MCP) server that lets Claude query Microsoft Clarity analytics — and lets a remote client connect to it from Claude Desktop, running entirely off your office PC.

---

1. How the pieces fit together

Your office PC
┌─────────────────────────────────────────────────┐
│  server.py  (FastMCP, listens on port 8000)      │
│     │                                            │
│     ├── clarity_client.py  → calls Clarity API   │
│     ├── cache.py           → saves your 10/day   │
│     │                        quota               │
│     └── bearer token auth  → blocks strangers     │
└─────────────────────┬─────────────────────────────┘
                       │
                  ngrok / Cloudflare Tunnel
                       │  (makes an outbound connection,
                       │   gives you a public https:// URL)
                       ▼
              https://your-tunnel-url.ngrok-free.app/mcp
                       │
                       ▼
              Claude Desktop (custom connector)

Four files do the actual work:

File	Job
exceptions.py	Defines specific error types (auth failed, bad input, rate-limited) so failures are readable, not raw tracebacks
cache.py	A simple 1-hour cache so repeat questions don't burn your 10-requests/day Clarity quota
clarity_client.py	The only file that talks to Clarity's real API — validates input, handles auth, parses responses
server.py	Wraps all of the above as 4 MCP tools, adds bearer-token auth, and serves it over HTTP instead of stdio

---

2. Why HTTP instead of stdio

Every MCP tutorial you'll find starts with stdio transport — the server and client run as one local process pair, no networking involved. That's great for testing on your own machine, but a client sitting elsewhere can't spawn a process on your PC. So this server uses streamable-HTTP transport instead: it's a normal web server listening on a port, reachable by URL, exactly like any REST API.

That single line does it:

mcp.run(transport="http", host="0.0.0.0", port=8000)

---

3. Why authentication is not optional here

The moment your server has a public URL, it's public — not "unlisted," actually public. Anyone who discovers the URL could call your Clarity tools and burn your 10 daily requests, or worse. So this server uses FastMCP's StaticTokenVerifier: a single secret string (MCP_ACCESS_TOKEN) that the client must send with every request as Authorization: Bearer <token>. No token, no access — verified above: requests without it get an immediate 401.

This token is not your Clarity API token. Think of it as a second, separate password — one you invent, one that only unlocks your MCP server, never Clarity directly.

---

4. Setup on your Windows PC (PowerShell)

# 1. Get the project onto your PC (copy this folder over, or unzip it)
cd C:\Users\<you>\clarity-mcp-server

# 2. Create and activate a virtual environment
python -m venv venv
.\venv\Scripts\Activate.ps1

# 3. Install dependencies
pip install -r requirements.txt

# 4. Create your real .env file from the example
Copy-Item .env.example .env
notepad .env

In .env, fill in:

• CLARITY_API_TOKEN — from Clarity dashboard: Settings → Data Export → Generate new API token
• MCP_ACCESS_TOKEN — invent one. Quick way:

  python -c "import secrets; print(secrets.token_urlsafe(32))"
  

  Paste the output in as MCP_ACCESS_TOKEN.

# 5. Run the server
python server.py

You should see Starting Clarity MCP server on http://0.0.0.0:8000/mcp. Leave this window open — closing it stops the server.

---

5. Making it reachable from outside the office (the tunnel)

Since the connecting client is remote and you can't port-forward on an office network, use a tunnel — it makes an outbound connection from your PC, so no firewall changes or IT tickets needed.

Option A — ngrok (fastest to test):

# one-time: download from https://ngrok.com/download, unzip, then:
.\ngrok.exe http 8000

It prints a URL like https://a1b2c3d4.ngrok-free.app — this forwards to your local port 8000. Free tier URLs change every restart; fine for demos, annoying for daily use.

Option B — Cloudflare Tunnel (more stable, still free):

winget install --id Cloudflare.cloudflared
cloudflared tunnel --url http://localhost:8000

Gives a similar public URL, and can be configured with a fixed subdomain if you set up a free Cloudflare account.

Either way, the client's connector URL becomes:

https://<your-tunnel-domain>/mcp

---

6. What to share with the connecting client

Two things, ideally over a secure channel (Teams DM, not email in plaintext):

1. The tunnel URL: https://your-tunnel-url/mcp
2. The MCP_ACCESS_TOKEN value from your .env

Their side (Claude Desktop): Settings → Connectors → Add custom connector → paste the URL → when prompted for a header, add:

Authorization: Bearer <the MCP_ACCESS_TOKEN you gave them>

Once connected, they can ask Claude things like "what's our traffic overview for the last 3 days?" and Claude will call your get_traffic_overview tool.

---

7. Testing it yourself first (recommended before sharing access)

# Terminal 1
python server.py

# Terminal 2 — simulate a request without a token (should fail with 401)
curl.exe -X POST http://localhost:8000/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}"

# With the token (should get further)
curl.exe -X POST http://localhost:8000/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "Authorization: Bearer YOUR_MCP_ACCESS_TOKEN" -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}"

---

8. Known limitations, said plainly

• Uptime is tied to your PC. Sleep, restart, or closing the terminal kills the connection. Fine for a scheduled demo, not for something a client relies on daily.
• 10 requests/day is Microsoft's hard limit, not something this code can raise. The cache buys you headroom, it doesn't remove the ceiling — after the cache TTL expires, a fresh question still spends a real request.
• Dimension names: the list in clarity_client.py (Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel, URL) matches Clarity's dashboard filters, but Microsoft doesn't publish one definitive canonical list, and multi-word dimensions have had quirks in the past (see microsoft/clarity#630 on GitHub). If a dimension call errors out unexpectedly, double check the exact spelling against your own Clarity dashboard's filter dropdown.
• Free ngrok URLs are not permanent — if you restart ngrok, the URL changes and you'll need to re-share it with the client.

---

9. If this becomes more than a demo

Running long-term off a desk PC + tunnel is a workaround, not a real deployment. If ongoing access is needed, the natural next step — especially since your office already uses Microsoft tooling — is deploying server.py to Azure App Service or a small Azure Container App, which gives you a permanent HTTPS URL, no tunnel, and no dependency on your PC staying on.