MCP Server
Heatmap MCP Server
Access Heatmap analytics within the AI tools you already use.
The Model Context Protocol (MCP) server connects your Heatmap data directly to Claude and other AI assistants. Ask a question in plain English — “What were my top converting pages last month?” — and get real data back. No dashboards, no exports, no SQL.
Why use the MCP?
Skip logging into dashboards and exporting reports. Describe what you want to know, and your AI assistant pulls live answers straight from your Heatmap account — including data you can’t get anywhere else, like per-element revenue attribution.
What you can do
Revenue, sessions & conversions
— ask about any metric in plain English
Page performance
— top pages by revenue, conversion rate, scroll depth, time on page
Comparisons
— week-over-week, month-over-month, before/after a change
Device & channel splits
— mobile vs desktop, paid vs organic, by country
Per-element revenue
— see which buttons and links actually drive revenue, not just clicks
Funnels
— find exactly where visitors drop off in checkout
User journeys
— where visitors go next, and where they came from
Custom events
— measure any interaction you’ve tagged
A/B test results
— conversion rates, revenue per visitor, statistical significance
By device
— compare variant performance on mobile vs desktop
List & find tests
— see every active and past experiment
CRO health checks
— run a site audit on demand
Prioritized recommendations
— what to test next, with ICE scoring
Full CRO reports
— structured, shareable reports built from your live data
Get started
MCP Server
Installation
The Heatmap MCP server is hosted — there’s nothing to download or run. Every client connects to the same URL and signs in with your Heatmap account.
Before you begin, make sure you have access to:
Heatmap account
— Active account with at least one tracked site
An AI client
— Claude, Claude Code, Cursor, ChatGPT, or Codex — see tabs below
AI subscription
— Some clients require a paid plan to add custom connectors
One URL, every client
Whichever tool you use, you’re pointing it at the same hosted server and approving access once:
https://mcp.heatmapcore.com/mcp
Choose your client
Open Settings → Connectors in Claude
Click + Add custom connector
Enter the name and server URL below
Click Add, then Connect
Log in to Heatmap and approve — you’re returned to Claude automatically
Name:
Heatmap MCP
Server:
https://mcp.heatmapcore.com/mcp
Requires a Claude plan with Connectors (Pro, Team, or Enterprise).
Run this in your terminal, then authenticate in the browser when prompted:
claude mcp add --transport http heatmap \
https://mcp.heatmapcore.com/mcp
Then run /mcp inside Claude Code and complete the login. Verify with claude mcp list.
Open Settings → Tools & MCP
Click + Add New MCP Server
Set Transport to streamable-http, name it Heatmap, and paste the URL
Save — a browser window opens to log in to Heatmap and approve
A green dot means it’s connected
Prefer editing config directly? Add to ~/.cursor/mcp.json:
{ "mcpServers": {
"heatmap": { "url": "https://mcp.heatmapcore.com/mcp" }
} }
Custom MCP connectors live in Developer Mode:
Open Settings → Apps & Connectors → Advanced settings and enable Developer Mode
Back in Apps & Connectors, click Add custom connector
Name it Heatmap and paste the server URL
Complete the Heatmap login when prompted
URL:
https://mcp.heatmapcore.com/mcp
Requires a paid ChatGPT plan (Plus, Pro, or Business+). Free ChatGPT can’t add custom connectors.
Add the server via the Codex CLI (shared with the IDE extension):
codex mcp add heatmap \
--url https://mcp.heatmapcore.com/mcp
codex mcp login heatmap
Config is stored in ~/.codex/config.toml and shared between the CLI and IDE extension.
Verify it worked
However you connected, confirm it’s live by asking your AI assistant one of our prompts, or any question you may have.
“List my Heatmap sites”
“What were my top pages by revenue last month?”
This will call the Heatmap MCP automatically and returns live data. The connection persists between sessions — no need to reconnect each time.
MCP Server
Prompts
What to ask, and how to ask it well. There’s no wrong way — just describe what you want to know.
Paste an example prompt straight into your AI assistant:
What is my revenue per session for the last 30 days?
Which pages have the highest conversion rate this month?
Where are visitors dropping off in my checkout funnel?
Which elements on my homepage are driving the most revenue?
How did last week compare to the week before?
What is my conversion rate on mobile vs desktop?
What are my top exit pages this month?
Summarize the results of my current split tests
Follow these tips for better results
Be specific about dates
— Say “last 30 days” or “June 2026” instead of “recently.”
Name the page
— “How is my checkout page doing?” beats “how are my pages doing?”
Ask for comparisons
— “How did last month compare to the month before?”
Ask follow-ups
— “Now break that down by device” — context carries over.
Request a report
— “Generate a complete CRO report” pulls everything into one summary.
Don’t overthink it
— There’s no wrong way to ask. Rephrase if needed — you can’t break anything.
MCP Server
Tools
You don’t need to know tool names — just describe what you want. Here’s everything that’s possible.
check your access level
The first tool your AI calls when you start a session. It checks your access key, confirms which sites and features you’re authorized to use, and sets up the session. You never call it yourself.
When to use
- Starting a new session with your AI assistant
- When the AI needs to know what you’re allowed to access
- Troubleshooting connection or permission issues
Example questions
- “What sites am I connected to?”
- “Do I have access to A/B test data?”
- “Check my Heatmap connection”
see all your Heatmap sites
Returns every website connected to your Heatmap account, with name, URL, and current status. The starting point for any question about a specific site — the AI uses it to find which site you mean.
When to use
- When you want to see all your connected sites
- When you’re not sure of a site’s exact name
- When switching between multiple stores or properties
Example questions
- “What sites do I have in Heatmap?”
- “List all my connected websites”
- “Show me my Heatmap properties”
switch to a specific site
Sets the “active site” for your session so all following questions apply to that property. With multiple sites, the AI asks you to pick one before pulling data. Once set, you don’t repeat the site name every time.
When to use
- When you want to analyse a specific site
- When switching from one store to another mid-conversation
- At the start of any analytics session
Example questions
- “Switch to my UK store”
- “Analyse my staging site instead”
- “I want to look at the blog site now”
list all tracked pages
Returns every page Heatmap is tracking on your active site, with page names and URLs. The AI uses this to find the right page when you ask about a specific section of your site.
When to use
- Finding the exact page name before a deep-dive
- Confirming which pages are being tracked
- Getting a full catalogue of your site’s pages
Example questions
- “What pages is Heatmap tracking on my store?”
- “Show me all the pages on my site”
- “Is my new landing page being tracked?”
answer any analytics question
The single most powerful tool in the Heatmap MCP. It runs one of 120+ pre-built operations against your live data — traffic, revenue, conversion, bounce, scroll depth, device splits, referrers, A/B results. The AI picks the right operation from what you ask.
When to use
- Asking about traffic, revenue, or conversion rates
- Comparing pages or time periods
- Device, channel, or geographic breakdowns
- Reviewing funnel performance or A/B test results
Example questions
- “What were my top 10 pages by revenue last month?”
- “What is my conversion rate on mobile vs desktop?”
- “Show me my site traffic trend over the past 90 days”
- “Which pages have the worst bounce rate?”
answer several questions at once
The same power as Talk to My Data, but runs up to four operations in a single request. Use it when you want a full picture in one go — traffic overview plus revenue by device plus top pages, returned together.
When to use
- When you want a comprehensive dashboard-style view
- When comparing multiple metrics at the same time
- For weekly or monthly performance summaries
Example questions
- “Give me a full site overview: traffic, revenue, and top pages”
- “Show me revenue by device AND top converting pages AND funnel summary”
- “What’s my traffic trend, bounce rate, and average order value this month?”
flexible raw analytics query
A more flexible tool for questions that don’t fit the standard 120+ operations. It breaks down sessions, pageviews, revenue, and other metrics by any combination of dimensions. The AI uses it as a fallback when Talk to My Data doesn’t cover your exact question.
When to use
- Unusual breakdowns or custom metric combinations
- Filtering by very specific session attributes
- When the AI needs to build a custom query
Example questions
- “Show me revenue from returning customers who came from email”
- “How many sessions did my product page get from paid search last week?”
- “Break down my sessions by country and device type”
week- or month-over-month comparison
Compares any two time periods side by side — current vs prior week, this month vs last, before a campaign vs after. Returns both periods plus the absolute and percentage change for every metric. Always used for “how did things change” questions.
When to use
- Week-over-week or month-over-month performance reviews
- Measuring the impact of a site change or campaign
- Before-and-after analysis for any event
Example questions
- “How did my revenue compare to last week?”
- “Did my conversion rate improve after the redesign?”
- “Compare this month’s traffic to the same month last year”
deep-dive into session behaviour
Returns detailed session-level data: how many sessions occurred, how long they lasted, how many pages were visited, and how those break down by device, source, or custom filters. Sessions are the unit of a visitor’s full visit.
When to use
- Understanding how visitors move through your site
- Analysing session length or pages-per-session
- Filtering sessions by new vs returning, purchase vs no purchase
Example questions
- “How long are visitors spending on my site on average?”
- “How many pages do buyers view before purchasing?”
- “Show me session data for mobile users only”
page-level traffic and engagement
Analyses traffic and engagement at the individual page level: how many people viewed each page, how long they stayed, how far they scrolled, and how that compares across pages or time periods.
When to use
- Comparing engagement across multiple pages
- Finding pages with high traffic but low time-on-page
- Checking scroll depth on key landing pages
Example questions
- “Which pages have the highest average time on page?”
- “How far are visitors scrolling on my product pages?”
- “Show me pageview data for my checkout page this week”
standardised page performance view
Returns a consistent, clean view of performance metrics for any page: traffic, revenue, engagement, and conversion data in a standardised format. Useful when you need a reliable, comparable snapshot of how a specific page is performing.
When to use
- Getting a clean summary for a single page
- Building page-level performance reports
- Comparing two specific pages on the same metrics
Example questions
- “Give me a full performance summary for my homepage”
- “How is my cart page performing this month?”
- “Compare my two product page templates on the same metrics”
revenue & click data for page elements
The core heatmap tool. Returns click data for every element on a page, showing how many clicks each received and — uniquely — how much revenue those clicks generated. This is the only heatmap in the world with per-element revenue attribution.
When to use
- Finding which buttons and links drive the most revenue
- Identifying elements that get clicks but no conversions
- Prioritising which page elements to redesign
Example questions
- “Which elements on my homepage are driving the most revenue?”
- “What’s getting the most clicks on my product page?”
- “Which CTA button on my checkout page is converting best?”
where do visitors go next?
Shows what pages visitors navigate to after viewing a specific page — and what pages they came from before. Reveals the actual paths people take through your site, not just the paths you designed.
When to use
- Understanding navigation flow through your site
- Finding unexpected drop-off points
- Identifying where buyers go before converting
Example questions
- “Where do visitors go after viewing my homepage?”
- “What page do most buyers visit just before checkout?”
- “Show me the most common paths through my site”
conversion funnel analysis
Analyses how visitors move through a defined sequence of pages (e.g. product → cart → checkout → confirmation), showing the conversion rate and drop-off at each step. Pinpoints exactly where you’re losing potential customers.
When to use
- Diagnosing checkout abandonment
- Finding the biggest drop-off in your purchase flow
- Comparing funnel performance across device types
Example questions
- “Where are people dropping off in my checkout funnel?”
- “What percentage of visitors who add to cart actually complete purchase?”
- “Compare my funnel conversion on mobile vs desktop”
conversion event details
Returns detailed data about conversion events (purchases and other goals): revenue generated, order values, timing, device type, and which pages were involved. Goes deeper than summary conversion rates to show the individual events.
When to use
- Analysing revenue from specific pages
- Reviewing order values by device or traffic source
- Auditing conversion events for a date range
Example questions
- “How much revenue did my product page generate last week?”
- “What’s the average order value from mobile visitors?”
- “Show me all conversions on my homepage this month”
track any custom action
Returns data for custom events you’ve set up in Heatmap — button clicks, form submissions, video plays, or any interaction you’ve explicitly tagged. Lets you measure exactly the actions that matter most to your business.
When to use
- Measuring specific interactions beyond standard clicks
- Tracking form completions or video engagement
- Analysing custom conversion goals
Example questions
- “How many people clicked my size guide button this month?”
- “Show me custom event data for my email signup form”
- “Which custom events are firing most on my product pages?”
custom event catalogue
Returns a list of all custom events defined in your Heatmap account, including event names and types. The AI uses it to find the right event name before querying event data.
When to use
- Seeing all the custom events you’ve set up
- Finding the exact name of a specific custom event
- Auditing which interactions are being tracked
Example questions
- “What custom events am I tracking?”
- “Do I have a custom event for wishlist adds?”
- “List all the events being tracked on my account”
list your A/B tests
Returns all the A/B tests (split tests) running on your account, including test names, variants, and IDs. The AI uses it to find the right test before pulling results.
When to use
- Seeing all active and past A/B tests
- Finding a specific test by name before reviewing results
- Getting a list of test IDs for deeper analysis
Example questions
- “What A/B tests do I have running right now?”
- “List all my split tests from this month”
- “What experiments are active on my checkout page?”
A/B test results
Returns the full results for a specific A/B test: conversion rates, revenue per visitor, statistical significance, and performance by device. Tells you whether your test is conclusive and which variant is winning.
When to use
- Reviewing results for a specific test
- Checking statistical significance before calling a winner
- Comparing test performance on mobile vs desktop
Example questions
- “What are the results of my homepage headline test?”
- “Is my checkout button colour test statistically significant?”
- “Show me A/B test results by device type”
expert CRO guidance
Gives your AI access to Heatmap’s built-in CRO knowledge: site health checks, investigation checklists, ICE scoring frameworks, conversion-drop diagnosis, and the full Billion Dollar Websites playbook. Use it any time you want expert guidance, not just data.
When to use
- Running a site health check
- Getting a prioritised list of what to test next
- Diagnosing a drop in conversion rate
- Learning best practices for specific page types
Example questions
- “Run a CRO health check on my site”
- “What should I be testing on my product pages?”
- “My conversion rate dropped last week — help me diagnose it”
- “What does the Billion Dollar Websites playbook say about checkout pages?”
standard CRO report formats
Returns the available CRO report templates your AI can use to structure an analysis. Three are available: Complete Site Report (full overview), Focused Performance Report (deep-dive on a single metric or page), and Experiment Diagnostic (A/B test analysis).
When to use
- When you want a structured report rather than a freeform answer
- Preparing a CRO report to share with your team
- Running a systematic analysis of your site
Example questions
- “Generate a complete CRO report for my store”
- “Give me a focused performance report for my checkout page”
- “Run an experiment diagnostic for my current A/B tests”
generate a full CRO report
Produces a complete, structured CRO report based on your live data. Combines traffic, revenue, heatmap, funnel, and test data into a narrative report with findings and recommendations. The highest-level tool — it orchestrates multiple queries and synthesises the results.
When to use
- Monthly or quarterly site performance reviews
- Pre-launch or post-launch analysis
- Preparing a report for stakeholders or clients
Example questions
- “Generate a complete CRO report for my store for last month”
- “Create a focused report on why my conversion rate dropped”
- “Give me an experiment diagnostic report for my current tests”
ad performance & revenue data
Returns analytics linked to your advertising, showing how paid traffic performs on revenue, conversion rate, and engagement compared to other sources. Helps you understand the quality of ad visitors, not just the volume. (Requires Heatmap Ads / AdKit.)
When to use
- Measuring the revenue quality of your paid traffic
- Comparing ad visitors vs organic visitors’ on-site behaviour
- Optimising landing pages for paid campaigns
Example questions
- “How is my paid traffic converting compared to organic?”
- “What’s the revenue per session for visitors from my Google Ads?”
- “Which landing pages are best for my paid campaigns?”
MCP Server
How it works
A thin, read-only bridge between your AI assistant and your Heatmap data.
When you ask a question, your AI client passes it to the Heatmap MCP server, which fetches the answer from your Heatmap account and returns it. The server never stores or changes your data — it only relays it.
Scope and privacy
- Read-only — Cannot modify your account or configuration
- Scoped — Only the sites authorized during connection
- Per-user — Each user connects with their own credentials
- Persistent — Stays connected between sessions — no need to reconnect each time
MCP Server
FAQ and troubleshooting
Common questions, and quick fixes for the usual hiccups.
Do I need to reconnect each session?
Does it work with Cursor or other AI tools?
What can it see — is my data safe?
What’s the difference between talk_to_my_data and get_analytics?
Do I need a paid Claude plan?
Troubleshooting
Still need help?
Knowledge base
intercom.help/heatmapcom/en
Book a demo
heatmap.com/book-demo
In-app chat
Use the widget in your portal
MCP Server
Changelog
Coming soon.