Umami is a privacy-first web and product analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place. No cookies, no surveillance, self-hosted or in the cloud.
TypeScript analyticsaudience-segmentationchartscohort-analysisgoogle-analyticsproduct-analyticsstatisticsuser-journeyweb-analytics
import { McpServer } from '@modelcontextprotocol/server';
import type { UmamiClient } from '@umami/api-client';
import { type McpLogger, silentLogger } from './lib/logger';
import { type AnyToolDefinition, registerTool, type ToolContext } from './lib/tool';
import { allTools } from './tools';
export const SERVER_NAME = 'umami';
export const SERVER_VERSION = '0.1.0';
export const SERVER_INSTRUCTIONS = `Umami is a privacy-focused web analytics platform. These tools answer questions about website traffic, visitors, pages, referrers, events, sessions and conversion reports.
Workflow:
1. Call list_websites to find the websiteId for the site the user is asking about (match by name or domain).
2. If unsure what dates have data, call get_website_daterange first.
3. Use get_website_stats for totals, get_website_traffic for trends over time, get_website_metrics for rankings (top pages, referrers, countries, browsers, campaigns, events), get_realtime for current visitors, get_event_stats / get_event_series for custom event totals and trends, get_event_properties to explore the custom data sent with events, get_session_stats for session counts, get_events / get_sessions / get_session to inspect individual activity, get_annotations to explain spikes with the team's dated notes, get_performance for Core Web Vitals, and run_funnel / run_journey / run_retention / run_attribution / get_revenue / get_goals for reports.
4. Saved definitions: list_funnels finds funnelIds for run_funnel, get_goals reports saved goals, and list_segments finds segment/cohort IDs to pass in filters.
Dates are ISO 8601 strings; endAt defaults to now. Results are paginated where noted — request another page rather than a huge pageSize. All tools are read-only.`;
export interface CreateUmamiMcpServerOptions {
/** API client carrying the caller's credentials. The MCP server never touches storage directly. */
client: UmamiClient;
/** Structured logger. Defaults to silent; the stdio CLI logs to stderr. */
logger?: McpLogger;
/** Identity for log correlation (never used for authorization). */
identity?: ToolContext['identity'];
/** Override the registered tool set (defaults to all read-only tools). */
tools?: AnyToolDefinition[];
}
/**
* Creates an MCP server whose tools call the Umami API through `@umami/api-client`.
* The same factory backs both the stdio CLI and the embedded HTTP endpoint.
*/
export function createUmamiMcpServer(options: CreateUmamiMcpServerOptions) {
const server = new McpServer(
{ name: SERVER_NAME, version: SERVER_VERSION },
{ instructions: SERVER_INSTRUCTIONS },
);
const context: ToolContext = {
client: options.client,
logger: options.logger ?? silentLogger,
identity: options.identity,
};
for (const tool of options.tools ?? allTools) {
registerTool(server, tool, context);
}
return server;
}