# MetricRaven

> Privacy-friendly web analytics with revenue attribution, funnels, goals, Search Console keywords and AI crawler tracking, all in one clean dashboard.

MetricRaven shows which channels, referrers, campaigns, pages, countries and devices bring visitors, conversions and revenue. Connect Stripe or RevenueCat, or send payments from your backend, to see where paying customers come from. It works before anyone accepts cookies and connects visits across days once storage is allowed.

- Website: https://metricraven.com
- Documentation: https://metricraven.com/docs
- Docs for AI agents and LLMs: https://metricraven.com/llms.txt (index) and https://metricraven.com/llms-full.txt (every page in one file)

Every documentation page has a Markdown version: add `.md` to its URL, for example https://metricraven.com/docs/quickstart → https://metricraven.com/docs/quickstart.md.

## Install

Paste the script before `</head>` in the website's shared layout so every page loads it. Replace `YOUR_SITE_ID` with the public site ID from the site's **Settings → Install** card; it is safe in browser code.

```html
<script
  defer
  src="https://metricraven.com/js/script.js"
  data-site-id="YOUR_SITE_ID"
></script>
```

- Quickstart: https://metricraven.com/docs/quickstart.md
- Install & verify (optional attributes, what is recorded): https://metricraven.com/docs/install.md
- Platform guides (Next.js, React, Vue/Nuxt, WordPress, Shopify, Webflow, Framer, Wix, Squarespace, Google Tag Manager, plain HTML): https://metricraven.com/docs/install-html.md
- Serve tracking from your own domain: https://metricraven.com/docs/proxy.md
- Troubleshooting: https://metricraven.com/docs/troubleshooting.md

## Keys and access tokens

Every API, MCP and CLI request sends a key as `Authorization: Bearer …`.

| Key | Use it for |
| --- | --- |
| Site secret key (`ana_sec_…`) | A server, for one website: sending events, payments and identify calls, reading that website's reports and deleting a person's data. Shown once when the website is added. |
| Account access token (`mr_…`) | The CLI, AI assistants (MCP) and scripts that work across websites. Limited to the scopes (read, visitors, write) and websites chosen in Settings → API & MCP (https://metricraven.com/app/api). |

Details: https://metricraven.com/docs/api-authentication.md

## MCP for AI assistants

MetricRaven runs a hosted MCP server; there is nothing to install. It uses the Streamable HTTP transport and an account access token sent as `Authorization: Bearer`.

- Server URL: https://metricraven.com/api/mcp
- Setup for Claude Code, Codex, Cursor, VS Code and Claude Desktop: https://metricraven.com/docs/mcp.md
- Tool reference: https://metricraven.com/docs/mcp-tools.md

```bash
claude mcp add --transport http metricraven https://metricraven.com/api/mcp \
  --header "Authorization: Bearer $METRICRAVEN_TOKEN"
```

Tools appear only when the token's scopes allow them:

- Reports (read): list_websites, get_traffic, get_breakdown, get_revenue, get_conversions, get_goal, get_insights, get_search_keywords, get_ad_spend, get_meta_ads, get_ai_crawlers, get_realtime, list_funnels, list_notes.
- Visitors (visitors scope): search_visitors, get_visitor.
- Changes (write scope): create_note, create_website, delete_payments and delete_goal_events (both count first and need confirm: true to delete).

The MCP server can't delete websites or people's data, or change billing. Limit: 240 requests a minute per token.

## CLI

Traffic, revenue, goals, visitors and websites from the terminal. Output is readable by default and JSON with `--json`, for scripts and agents that run shell commands. Node.js 20 or later.

```bash
npm install -g @metricraven/cli
metricraven login                   # paste an access token at the hidden prompt
metricraven websites list
metricraven use <website_id>
metricraven analytics traffic --period 7d
metricraven analytics breakdown referrer --sort revenue --limit 20 --json
```

`METRICRAVEN_TOKEN` (access token), `METRICRAVEN_SITE` (default website ID) and `METRICRAVEN_API_BASE` override the saved configuration.

- Get started: https://metricraven.com/docs/cli.md
- Command reference: https://metricraven.com/docs/cli-commands.md

## REST API

All paths begin with https://metricraven.com/api/v1. Report endpoints take the website as `site`.

- Authentication: https://metricraven.com/docs/api-authentication.md
- Reports API (traffic, breakdowns, conversions, revenue, insights, search, crawlers, live): https://metricraven.com/docs/reports-api.md
- Account API (list and create websites): https://metricraven.com/docs/account-api.md
- Payments API: https://metricraven.com/docs/payments-api.md
- Server events: https://metricraven.com/docs/server-events.md
- Link users to visits (identify): https://metricraven.com/docs/identify-users.md
- Bots & AI crawlers: https://metricraven.com/docs/bots-ai-crawlers.md
- Delete a person's data: https://metricraven.com/docs/delete-person-data.md

## Agent guidance

When helping someone with MetricRaven:

1. Prefer MCP when the assistant supports it and needs to read the user's analytics.
2. Prefer the CLI (with `--json`) in terminal-based coding agents or when MCP is unavailable.
3. Use the REST API with the site secret key for backend integrations: events, payments, identify calls and reports.
4. Read docs programmatically from the `.md` URLs listed below.
5. Never ask the user to paste a site secret key or access token into chat, and never put either in browser code, a public repository or a URL. Use `METRICRAVEN_TOKEN`, `metricraven login` or the client's own configuration.
6. Ask for a token with the fewest scopes needed: read for reports, visitors only for names, emails and journeys, write only to add websites or chart notes.
7. For missing visits or revenue, start with https://metricraven.com/docs/troubleshooting.md.

## Docs

### Get started

Install the tracker and see your first visit.

- [Quickstart](https://metricraven.com/docs/quickstart.md): Create a site, install the script and see your first pageview in a few minutes.
- [Install & verify](https://metricraven.com/docs/install.md): Add the MetricRaven script to every page, confirm data is arriving and configure optional attributes.
- [Exclude your visits](https://metricraven.com/docs/exclude-visits.md): Keep your own browsing, admin pages, staging hosts and office IPs out of your reports.
- [Consent & visitor IDs](https://metricraven.com/docs/consent.md): How visitor IDs work before and after storage consent, and how to connect your cookie banner.
- [Change or cancel your plan](https://metricraven.com/docs/change-plan.md): Upgrade right away with a prorated charge, downgrade at the end of your billing period, cancel and resume, switch between monthly and yearly, and find your invoices.

### Installation guides

Where to paste the script on your platform.

- [Installation guides](https://metricraven.com/docs/install-guides.md): Step-by-step guides for adding MetricRaven to your framework, CMS, website builder or AI app builder.
- [Install on a plain HTML site](https://metricraven.com/docs/install-html.md): Add MetricRaven to hand-written HTML pages or a static site generator's base layout.
- [Install on Next.js](https://metricraven.com/docs/install-nextjs.md): Load the MetricRaven script with next/script in the App Router or Pages Router.
- [Install on React (Vite)](https://metricraven.com/docs/install-react.md): Add MetricRaven to a Vite React app through index.html.
- [Install on React Router](https://metricraven.com/docs/install-react-router.md): Add MetricRaven to a React Router v7 app in framework mode (server or SPA) or library mode.
- [Install on Vue or Nuxt](https://metricraven.com/docs/install-vue-nuxt.md): Add MetricRaven to a Vite Vue app's index.html or a Nuxt app's head configuration.
- [Install on Astro](https://metricraven.com/docs/install-astro.md): Add MetricRaven to the shared layout of an Astro site.
- [Install on Django](https://metricraven.com/docs/install-django.md): Add MetricRaven to the base template your Django pages extend.
- [Install on Laravel](https://metricraven.com/docs/install-laravel.md): Add MetricRaven to your Laravel Blade layout, including Inertia and Livewire apps.
- [Install on WordPress](https://metricraven.com/docs/install-wordpress.md): Install the MetricRaven WordPress plugin: paste your site ID, exclude admins, connect your consent banner and attribute WooCommerce orders.
- [Install on Ghost](https://metricraven.com/docs/install-ghost.md): Add MetricRaven to a Ghost site with Code injection, or in your theme.
- [Install on Shopify](https://metricraven.com/docs/install-shopify.md): Add MetricRaven to your Shopify theme's theme.liquid layout.
- [NPM package (@metricraven/web)](https://metricraven.com/docs/npm-package.md): Install MetricRaven from npm in Next.js, React, Vue or Svelte, with typed track, identify, pageview and consent calls.
- [Install on Webflow](https://metricraven.com/docs/install-webflow.md): Add MetricRaven through Webflow's site-wide custom code head setting.
- [React Native & Expo](https://metricraven.com/docs/react-native.md): Track screens, events and signed-in users in React Native and Expo apps, with an offline queue and consent.
- [Install on Framer](https://metricraven.com/docs/install-framer.md): Add MetricRaven through Framer's site settings custom code, then publish.
- [Node.js and server SDK (@metricraven/node)](https://metricraven.com/docs/node-sdk.md): Send goals, identify, payments, refunds and crawler hits from Node, Bun, Deno, Cloudflare Workers or Vercel Edge with typed calls.
- [Install on Wix](https://metricraven.com/docs/install-wix.md): Add MetricRaven to every page of a Wix site with Custom Code.
- [Install on Squarespace](https://metricraven.com/docs/install-squarespace.md): Add MetricRaven to every page of a Squarespace site with Code Injection.
- [Install on Bubble](https://metricraven.com/docs/install-bubble.md): Add MetricRaven to every page of a Bubble app from the SEO / metatags settings.
- [Install on Kajabi](https://metricraven.com/docs/install-kajabi.md): Add MetricRaven to Kajabi site pages with Page scripts and to checkout with the checkout tracking code.
- [Install on Podia](https://metricraven.com/docs/install-podia.md): Add MetricRaven to your Podia site and checkout with the website tracking code setting.
- [Install on Lovable](https://metricraven.com/docs/install-lovable.md): Add MetricRaven to a Lovable app by asking Lovable, or by editing the code yourself.
- [Install on Bolt](https://metricraven.com/docs/install-bolt.md): Add MetricRaven to a Bolt.new project by prompting Bolt or editing the code, then publish.
- [Install on v0](https://metricraven.com/docs/install-v0.md): Add MetricRaven to a v0 app by prompting v0 or editing app/layout.tsx, then publish to Vercel.
- [Install on Replit](https://metricraven.com/docs/install-replit.md): Add MetricRaven to a Replit app by asking Agent or editing the HTML head, then publish.
- [Install with Google Tag Manager](https://metricraven.com/docs/install-google-tag-manager.md): Load MetricRaven from a Custom HTML tag that fires on all pages.

### Revenue

Connect payments and link them to visits.

- [Connect your payment provider](https://metricraven.com/docs/connect-payment-provider.md): Pick your payment provider and how customers pay (Stripe Checkout, Payment Links, Lemon Squeezy, Paddle, Polar, Shopify and more) to get the two guides that put revenue on your analytics.
- [Revenue dashboard](https://metricraven.com/docs/revenue-dashboard.md): What the Revenue tab shows: MRR, new revenue vs renewals vs refunds, subscriptions, subscription events, paid acquisition, customers and lifetime value.
- [Reporting currency & FX](https://metricraven.com/docs/reporting-currency.md): How MetricRaven shows revenue from several currencies in one: the reporting currency, ECB daily rates, and what happens when a rate is missing.
- [Connect Stripe](https://metricraven.com/docs/stripe.md): Import Stripe payments with a read-only restricted key and attribute checkouts to website visits.
- [Attribute Stripe Checkout payments](https://metricraven.com/docs/stripe-checkout.md): Pass the MetricRaven visitor ID into Stripe Checkout Session metadata so each payment links to its visit.
- [Attribute Stripe PaymentIntents](https://metricraven.com/docs/stripe-payment-intents.md): Add the MetricRaven visitor ID to PaymentIntent or subscription metadata for custom Stripe payment flows.
- [Attribute Stripe Payment Links](https://metricraven.com/docs/stripe-payment-links.md): What MetricRaven can and can't attribute for Stripe Payment Links, and a webhook that links them to visits.
- [Other Stripe payment methods](https://metricraven.com/docs/stripe-other-methods.md): Attribute Stripe invoices, customer-level payments and other flows, and see exactly which fields MetricRaven reads.
- [Connect RevenueCat](https://metricraven.com/docs/revenuecat.md): Receive RevenueCat purchase, renewal and refund events through an authenticated webhook.
- [Connect Lemon Squeezy](https://metricraven.com/docs/lemonsqueezy.md): Receive Lemon Squeezy orders, renewals and refunds through a signed webhook and attribute them to visits.
- [Other Lemon Squeezy methods](https://metricraven.com/docs/lemonsqueezy-other-methods.md): Attribute Lemon Squeezy payments by the customer's email when the checkout can't carry the visitor ID.
- [Connect Polar](https://metricraven.com/docs/polar.md): Receive Polar orders, renewals and refunds through a signed webhook and attribute them to visits.
- [Other Polar methods](https://metricraven.com/docs/polar-other-methods.md): Attribute Polar payments by the customer's email when the checkout can't carry the visitor ID.
- [Connect Paddle](https://metricraven.com/docs/paddle.md): Receive Paddle Billing transactions and refunds through a signed webhook and attribute them to visits.
- [Other Paddle methods](https://metricraven.com/docs/paddle-other-methods.md): Attribute Paddle payments by the customer's email when the checkout can't carry the visitor ID.
- [Connect Dodo Payments](https://metricraven.com/docs/dodo-payments.md): Receive Dodo Payments payments, renewals and refunds through a signed webhook and attribute them to visits.
- [Connect WooCommerce](https://metricraven.com/docs/woocommerce.md): Receive WooCommerce orders and refunds through a signed webhook and attribute them to visits.
- [Connect Shopify](https://metricraven.com/docs/shopify.md): Receive Shopify orders and refunds through signed webhooks and attribute them to visits.
- [Attribute payments by email](https://metricraven.com/docs/attribute-by-email.md): Credit provider payments to the right visit with the buyer's email when the checkout can't carry the visitor ID.
- [Attribute revenue with Podia](https://metricraven.com/docs/attribution-guide-with-podia.md): Credit Podia course, download and membership sales to the visits that brought the buyer, through Stripe.
- [Attribute revenue with Kajabi](https://metricraven.com/docs/attribution-guide-with-kajabi.md): Credit Kajabi course, coaching and membership sales to the visits that brought the buyer, through Stripe.
- [Attribute revenue with Ghost](https://metricraven.com/docs/attribution-guide-with-ghost.md): Credit paid Ghost memberships to the visits that brought the member, through Stripe.
- [Payments API](https://metricraven.com/docs/payments-api.md): Send payments and refunds from a custom payment system with your site's secret key.
- [Link users to visits](https://metricraven.com/docs/identify-users.md): Connect signed-in users to their visits from the browser or your backend, with optional profile traits.
- [Send verified server events](https://metricraven.com/docs/server-events.md): Report actions your backend can confirm, such as account creation, as goals.

### Features

Reports, goals, filters and sharing.

- [Dates, filters & segments](https://metricraven.com/docs/filters-segments.md): Choose reporting periods and timezones, filter visitors, save segments and read chart metrics.
- [Goals & funnels](https://metricraven.com/docs/goals-funnels.md): Track clicks, visible sections and JavaScript actions as goals, then chain them into funnels.
- [Explore visitors](https://metricraven.com/docs/visitor-explorer.md): Search the visitors in a reporting period and open their complete journey.
- [Realtime visitors](https://metricraven.com/docs/realtime.md): See who is on your site right now on a globe or flat map, follow the live activity feed, replay the last 8 hours and estimate what the visitors online are worth.
- [Buyer insights](https://metricraven.com/docs/buyer-insights.md): Compare paying visitors with everyone else, see when people buy and what they did first.
- [Campaign & referral links](https://metricraven.com/docs/campaign-links.md): Tag links with UTM and ref/source/via parameters, compare them in Acquisition and Campaigns, and see how channels such as AI and Affiliate are grouped.
- [Meta Ads spend and ROAS](https://metricraven.com/docs/meta-ads.md): Connect a Facebook and Instagram ad account to see spend, attributed revenue, ROAS and cost per customer for every Meta campaign, ad set and ad.
- [Google Ads spend and ROAS](https://metricraven.com/docs/google-ads.md): Connect a Google Ads account to see spend, attributed revenue, ROAS and cost per customer for every Google campaign, ad group, ad and Performance Max asset group, next to Meta Ads.
- [Connect Google Search Console](https://metricraven.com/docs/search-console.md): Authorize read-only Search Console access to see Google keywords, clicks and estimated revenue.
- [Bots & AI crawlers](https://metricraven.com/docs/bots-ai-crawlers.md): Track GPTBot, ClaudeBot, Perplexity and other crawlers from your server with @metricraven/ai-crawl and an ingest-only bot token, or report them through the API.
- [Bot traffic settings](https://metricraven.com/docs/bot-traffic-settings.md): Choose which crawler companies and agents are recorded, send crawl events with an ingest-only bot token, and track the bot request allowance.
- [AI visibility: what assistants say about you](https://metricraven.com/docs/ai-visibility.md): Track the questions buyers ask ChatGPT, Claude, Perplexity, Gemini, Grok and Google's AI Mode and AI Overviews, and see whether the answers mention you, in what position, and which pages they cite.
- [Share & embed](https://metricraven.com/docs/share-embed.md): Create a read-only dashboard link, embed it in an iframe and sync its theme with your app.
- [Team members and roles](https://metricraven.com/docs/team-members.md): Invite teammates to a website as admins or viewers, transfer ownership, and rotate the site's secret key.
- [Dashboard appearance](https://metricraven.com/docs/appearance.md): Set your dashboard's light and dark background and graph colors, including for shares and embeds.
- [SPA & virtual pages](https://metricraven.com/docs/spa-virtual-pages.md): Track single-page-app routes automatically, send manual pageviews for virtual screens and opt in to hash routes or plain #anchors.
- [Cross-domain tracking](https://metricraven.com/docs/cross-domain.md): Keep one visitor across separate domains of the same site, such as a landing site and an app, with consent-aware, short-lived links.
- [Conversion alerts](https://metricraven.com/docs/goal-alerts.md): Get an email when someone completes a goal, pays, or becomes a new customer, with where they came from.
- [Track X and Reddit mentions](https://metricraven.com/docs/social-mentions.md): See posts on X and Reddit that mention your website or brand right on the traffic chart.
- [Traffic spike alerts](https://metricraven.com/docs/traffic-spike-alerts.md): An email when your site suddenly gets far more visitors than usual, with the sources behind it.
- [Attribute traffic and revenue to X posts](https://metricraven.com/docs/x-link-attribution.md): See the actual X posts that sent visitors and revenue instead of t.co links.
- [Weekly & monthly email reports](https://metricraven.com/docs/email-reports.md): A Monday-morning summary of visitors, revenue and top sources, compared with the week before.
- [Chart notes](https://metricraven.com/docs/chart-notes.md): Mark launches, campaigns and releases on the traffic chart, so you remember later why the numbers moved.
- [GitHub commits on your chart](https://metricraven.com/docs/github.md): Connect a repository to see commits next to traffic and revenue, and spot which releases moved the numbers.
- [Import from Plausible](https://metricraven.com/docs/import-from-plausible.md): Bring your Plausible Analytics history into MetricRaven from an export ZIP or the Stats API, as daily totals labelled as imported.

### Proxy

Serve tracking from your own domain.

- [Managed proxy](https://metricraven.com/docs/managed-proxy.md): Serve the MetricRaven script and events from your own subdomain with one CNAME record. MetricRaven handles routing and the certificate.
- [Serve tracking from your own domain](https://metricraven.com/docs/proxy.md): How a same-origin proxy for the MetricRaven script and events works, and recipes for your stack.
- [Proxy with Next.js](https://metricraven.com/docs/proxy-nextjs.md): Serve the MetricRaven script and events from your Next.js app with one App Router route handler.
- [Proxy with Express](https://metricraven.com/docs/proxy-express.md): Serve the MetricRaven script and events from an Express server on Node.js.
- [Proxy with Flask](https://metricraven.com/docs/proxy-flask.md): Serve the MetricRaven script and events from a Flask app.
- [Proxy with FastAPI](https://metricraven.com/docs/proxy-fastapi.md): Serve the MetricRaven script and events from a FastAPI app.
- [Proxy with PHP](https://metricraven.com/docs/proxy-php.md): Serve the MetricRaven script and events from one plain PHP file with curl.
- [Proxy with Laravel](https://metricraven.com/docs/proxy-laravel.md): Serve the MetricRaven script and events from a Laravel app with the HTTP client.
- [Proxy with Astro](https://metricraven.com/docs/proxy-astro.md): Serve the MetricRaven script and events from an Astro server endpoint.
- [Proxy with Vue or Nuxt](https://metricraven.com/docs/proxy-vue-nuxt.md): Proxy the MetricRaven script and events in the Vite dev server for Vue, or with a Nuxt server route.
- [Proxy with Nginx](https://metricraven.com/docs/proxy-nginx.md): Serve the MetricRaven script and events through Nginx with two location blocks.
- [Proxy with Caddy](https://metricraven.com/docs/proxy-caddy.md): Serve the MetricRaven script and events through Caddy's reverse_proxy.
- [Proxy with Cloudflare Workers](https://metricraven.com/docs/proxy-cloudflare-workers.md): Serve the MetricRaven script and events from a Cloudflare Worker on your own domain.
- [Proxy with Vercel](https://metricraven.com/docs/proxy-vercel.md): Use vercel.json rewrites and a Vercel Function to serve MetricRaven from your domain.
- [Proxy with Netlify](https://metricraven.com/docs/proxy-netlify.md): Serve the MetricRaven script and events from a Netlify Function on your own domain.
- [Proxy with Firebase Hosting](https://metricraven.com/docs/proxy-firebase.md): Rewrite two Firebase Hosting paths to a Cloud Function that relays MetricRaven.
- [Proxy with DigitalOcean App Platform](https://metricraven.com/docs/proxy-digitalocean.md): Route /a on App Platform to a small proxy service that forwards the visitor IP from do-connecting-ip.

### API reference

Read reports, manage websites and delete personal data from your backend.

- [API overview](https://metricraven.com/docs/api-overview.md): Base URL, which key to use for each endpoint, the site parameter, response and error formats, rate limits, pagination and date ranges.
- [Authentication and access tokens](https://metricraven.com/docs/api-authentication.md): Choose between a site secret key and an account access token, and give each token only the access it needs.
- [Reports API](https://metricraven.com/docs/reports-api.md): Every report endpoint with its parameters and response fields: traffic, breakdowns, conversions, goals, insights, revenue, subscriptions, search, crawlers, X links, mentions, realtime and visitors.
- [Notes, funnels and site settings API](https://metricraven.com/docs/site-api.md): Create chart notes, read GitHub commits, save funnels and segments, and read or change a website's settings through the API.
- [Visitors and people API](https://metricraven.com/docs/visitors-api.md): Read one visitor's full profile and timeline, find visitors and journeys, and erase a person's data.
- [Delete a person's data](https://metricraven.com/docs/delete-person-data.md): Erase one person's analytics events and identity records from the dashboard or the API.
- [Account API](https://metricraven.com/docs/account-api.md): Manage websites, access tokens, team members and your profile, and check who an access token belongs to.
- [API playground](https://metricraven.com/docs/api-playground.md): Try the MetricRaven API from your browser: pick an endpoint, fill the parameters, send it with your key and see the response.

### MCP

Ask Claude, ChatGPT, Cursor and other AI assistants about your analytics.

- [Connect AI assistants with MCP](https://metricraven.com/docs/mcp.md): Connect Claude, ChatGPT, Cursor, VS Code, Codex and other MCP clients with OAuth and ask about your traffic, revenue and goals.
- [ChatGPT app](https://metricraven.com/docs/chatgpt-app.md): Ask ChatGPT about your MetricRaven traffic, revenue, goals and funnels, with interactive charts and access limited to the websites you approve.
- [MCP tool reference](https://metricraven.com/docs/mcp-tools.md): Every tool the MetricRaven MCP server offers, its inputs and the scope it needs.

### CLI

Query analytics and manage websites from your terminal.

- [MetricRaven CLI](https://metricraven.com/docs/cli.md): Install the CLI, log in with an access token and read your analytics from the terminal.
- [CLI command reference](https://metricraven.com/docs/cli-commands.md): Every metricraven command, its options and the access it needs.

### Troubleshooting

Fix missing visits, revenue and connections.

- [Troubleshooting](https://metricraven.com/docs/troubleshooting.md): Fix missing visits, unattributed revenue, empty integrations and lost keys.
- [Script blocked by Content Security Policy (CSP)](https://metricraven.com/docs/content-security-policy.md): No visits because a Content Security Policy blocks the MetricRaven script or its requests? Allow it in script-src and connect-src, with examples for Next.js, Vercel, Netlify, Nginx, Apache and WordPress.