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.

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