Mouseflow MCP Server

An MCP (Model Context Protocol) server that wraps the Mouseflow public API, letting any MCP-compatible AI assistant query your Mouseflow analytics — websites, recordings, heatmaps, funnels, forms, feedback, aggregated metrics, friction insights, and flow/journey analysis.

Requirements

• Node.js 18 or newer (nodejs.org)
• A Mouseflow account with an API key (Account → API Keys)
• An MCP-compatible client

Install

Option 1: Install via npm (recommended)

npm install -g @mouseflow-utils/mouseflow-mcp

Option 2: Run the latest version with npx without installing

npx @mouseflow-utils/mouseflow-mcp

Configuration

The server reads these environment variables, typically set by your MCP client:

| Variable | Required | Description | |----------|----------|-------------| | MOUSEFLOW_EMAIL | Yes | The email on your Mouseflow account | | MOUSEFLOW_API_KEY | Yes | Your Mouseflow API key | | MOUSEFLOW_DATACENTER | No | us (default) or eu |

Client setup

Most MCP clients accept a JSON configuration block like the one below. Register a new MCP server named mouseflow.

If you installed globally (Option 1):

{
  "mcpServers": {
    "mouseflow": {
      "command": "mouseflow-mcp",
      "env": {
        "MOUSEFLOW_EMAIL": "[email protected]",
        "MOUSEFLOW_API_KEY": "your-api-key",
        "MOUSEFLOW_DATACENTER": "us"
      }
    }
  }
}

If you're using npx (Option 2):

{
  "mcpServers": {
    "mouseflow": {
      "command": "npx",
      "args": ["@mouseflow-utils/mouseflow-mcp"],
      "env": {
        "MOUSEFLOW_EMAIL": "[email protected]",
        "MOUSEFLOW_API_KEY": "your-api-key",
        "MOUSEFLOW_DATACENTER": "us"
      }
    }
  }
}

The exact config file location and format varies by client — consult your client's MCP documentation. Restart the client afterward so it picks up the new server.

Available tools

Websites & recordings

| Tool | Description | |------|-------------| | list_websites | List all websites in the account | | get_website | Get details for a specific website | | list_recordings | List recorded sessions with rich filtering (date, device, country, tags, vars, friction, etc.) | | get_recording | Get recording details including pageviews | | list_tags | List all recording tags | | list_variables | List all custom variable keys |

Pages & heatmaps

| Tool | Description | |------|-------------| | list_pages | List pages with heatmap statistics | | get_page_heatmap | Get heatmap details for a specific page URL |

Funnels

| Tool | Description | |------|-------------| | list_funnels | List all funnels (supports date filtering) | | get_funnel | Get funnel report with conversion rates per step | | get_funnel_conversion_timeseries | Get funnel conversion rates bucketed over time (day/week/month) |

Forms & feedback

| Tool | Description | |------|-------------| | list_forms | List tracked forms (supports date filtering) | | get_form | Get form analytics with field-level conversion data | | list_feedback | List feedback campaigns with date-filtered report data (impressions, responses, replies) | | get_feedback_response | Get a single campaign's replies with optional date filter and limit |

Aggregated metrics

| Tool | Description | |------|-------------| | get_pageview_metrics | Aggregated page-level metrics (views, clicks, scroll, friction, etc.) grouped by page, device, country, UTM params, etc. Supports timeseries. | | get_session_metrics | Aggregated session-level metrics (sessions, visitors, engagement, errors, friction) grouped by country, device, entry/exit page, UTM params, etc. Supports timeseries. |

Friction insights

| Tool | Description | |------|-------------| | get_top_friction_items | Ranked list of pages/elements with friction issues (worst pages, click errors, 404s, slow-loading pages, etc.) | | get_friction_breakdown | Friction distribution by type (site-wide) or detailed stats for a specific page | | get_friction_timeseries | Friction trends bucketed over time, site-wide or per page |

Flows / journeys

| Tool | Description | |------|-------------| | get_flow_data | Get journey/path data showing what pages users visit before and after a focus page |

Troubleshooting

mouseflow-mcp: command not found Run npm install -g @mouseflow-utils/mouseflow-mcp again and check that npm's global bin directory is in your shell's PATH — on macOS usually /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel), on Windows %APPDATA%\npm.

The MCP server doesn't appear in your client Check the client's MCP log for errors mentioning mouseflow. The most common causes are missing MOUSEFLOW_EMAIL/MOUSEFLOW_API_KEY, or MOUSEFLOW_DATACENTER set to something other than us or eu.

401 Unauthorized Credentials are wrong, or your account is on the other datacenter. Swap MOUSEFLOW_DATACENTER between us and eu and try again.

422 Unprocessable Entity The tool sent parameters the Mouseflow backend rejected. Please report it with the full error message, the tool name, and the arguments used.

Support

For help or to report issues, contact [email protected].

Updating

Option 1 (global install):

npm install -g @mouseflow-utils/mouseflow-mcp@latest

Option 2 (npx): No action needed — npx always fetches the latest version automatically.

No config changes needed — just restart your MCP client.