UserFlux MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to your UserFlux analytics data. Query your ClickHouse analytics tables, explore your data dictionary, and understand your table schemas — all through natural language.

Setup

1. Get your MCP API key

Find your MCP API key in your UserFlux dashboard under Settings > API Keys.

2. Configure your MCP client

Add the following to your MCP client configuration:

Claude Desktop (claude_desktop_config.json):

{
	"mcpServers": {
		"userflux": {
			"command": "npx",
			"args": ["-y", "@userflux/mcp-server"],
			"env": {
				"USERFLUX_API_KEY": "your-mcp-api-key-here"
			}
		}
	}
}

Claude Code (.mcp.json):

{
	"mcpServers": {
		"userflux": {
			"command": "npx",
			"args": ["-y", "@userflux/mcp-server"],
			"env": {
				"USERFLUX_API_KEY": "your-mcp-api-key-here"
			}
		}
	}
}

Tools

get_data_dictionary

Returns your workspace's data dictionary — all tracked events with their properties and data types, profile properties, device properties, and location properties. Call this first to understand what data is available.

execute_analytics_query

Execute a read-only ClickHouse SQL query against your analytics data. Use template table names:

• eventsTable — user events
• profilesTable FINAL — user profiles (use FINAL for latest state)
• activityTable — system activity
• productsTable FINAL — products (use FINAL for latest state)

Results are limited to 1000 rows.

get_table_schemas

Returns the ClickHouse table column definitions and SQL query guidelines for all analytics tables.

list_workflows

Lists every workflow in your workspace (published, draft, and archived) with id, description, status, campaign tag, conversion goal event, and trigger/step counts. Use this to discover available workflows before analysing their performance via the activity table.

get_workflow

Gets full details of a single workflow by id — description, status, conversion goal configuration, triggers (how users enter) and steps (actions taken). Pair with execute_analytics_query against the activity table (props.workflowId::String = '<id>') to measure performance or list users who converted.

get_campaign_performance_stats

Returns pre-aggregated performance stats for a workflow — total entries, unique users entered, reach against the identified user base, conversions against the workflow's configured conversion goal event, and conversion rate. Requires the workflow to have a conversion goal configured. Faster than composing the equivalent SQL with execute_analytics_query.

Resources

userflux://sql-guidelines

ClickHouse SQL guidelines and best practices for querying UserFlux analytics tables.

Environment Variables

| Variable | Required | Default | Description | | ------------------ | -------- | --------------------------------- | -------------------------------------------- | | USERFLUX_API_KEY | Yes | — | Your MCP API key from the UserFlux dashboard | | USERFLUX_API_URL | No | https://metrics-api.userflux.co | API base URL |

Development

npm install
npm run build
npm start