Umami Web Intelligence Connector Server

This Model Context Protocol (MCP) node bridges Claude's analytical capacity with granular web performance telemetry sourced from the Umami service. It empowers Claude to deeply examine audience conduct, monitor site health, and generate evidence-based conclusions.

The entire operational codebase was architected and realized using Claude Sonnet 3.5 alongside the Cursor IDE.

Core Functionality

This intermediary server establishes a connection to your designated Umami analytics infrastructure, empowering Claude to perform the following operations:

Deconstruct user navigation paths and behavioral traits
Assess key indicators of website performance
Provide telemetry on concurrent user counts in real-time
Retrieve and interpret the structure and content of site pages
Synthesize inferences from long-term statistical records

Operational Mechanism

The server exposes a suite of capabilities to Claude for the systematic analysis of website data:

Exposed Utilities

fetch_sites_inventory: Obtain a catalog of monitored web properties and their unique identifiers within your Umami tenant.
retrieve_site_summary: Fetch primary performance statistics, such as total page views, unique visitors, and session abandonment rates for a specified property.
fetch_detailed_metrics: Deep-dive analysis into specific dimensions: landing page URLs, traffic sources (referrers), user agents (browsers), and geographic origins.
query_pageview_timeseries: Extract time-indexed sequences of page view counts, configurable by chosen temporal resolution.
monitor_live_users: Report the current census of active users interacting with the website property.
get_session_identifiers: List unique session IDs correlated with particular interactions or within specified time frames.
fetch_session_trace: Retrieve the comprehensive sequence of events comprising a specific user session ID.
semantic_journey_lookup: Execute targeted semantic retrieval across numerous user paths, yielding the most contextually relevant data segments for a given analytical query, thereby mitigating context window limitations.
capture_visual_snapshot: Generate high-fidelity visual representations (screenshots) of designated web pages.
fetch_page_source: Retrieve and parse the underlying HyperText Markup Language (HTML) source code of a web asset.

Each utility is defined with a precise function signature and parameter schema to furnish Claude with necessary context, facilitating accurate utility selection and argument population for task resolution.

Most utilities interface directly with the Umami API to pipe data into the Claude Desktop environment. However, semantic_journey_lookup incorporates an extra layer: a vector similarity search step to circumvent Claude's context buffer constraints and optimize token consumption. User journey records for an event are first aggregated via the Umami API, subsequently segmented into smaller textual units, and then transformed into dense vector embeddings using an open-source sentence transformer model sourced from Hugging Face. Based on the investigative question, the most germane embeddings are retrieved and presented to Claude, enabling fine-grained examination of discrete user actions and navigation patterns—a level of detail often elusive with conventional data visualization paradigms. The implementation details for this embedding and search mechanism reside in src/analytics_service/embeddings.py.

Furthermore, the capture_visual_snapshot and fetch_page_source utilities leverage the open-source Crawl4AI web scraping engine to acquire HTML source and page imagery. To prevent context overflow in Claude, captured screenshots undergo necessary downsampling. This capability furnishes Claude with structural and aesthetic context regarding the website's layout, leading to more precise and pertinent recommendations for performance enhancement. The web crawler's operational logic is encapsulated within src/analytics_service/crawler.py.

Deployment Instructions

Prerequisites

Install uv: pip install uv
Claude Desktop Configuration Setup

Modify your Claude Desktop configuration file (claude_desktop_config.json) at the following location: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json

Incorporate the following configuration block:

json { "mcpServers": { "analytics_service": { "command": "uv", "args": [ "--directory", "/path/to/analytics_service", "run", "analytics-service" ], "env": { "UMAMI_API_URL": "https://example.com", "UMAMI_USERNAME": "yourUmamiUsername", "UMAMI_PASSWORD": "yourUmamiPassword", "UMAMI_TEAM_ID": "yourUmamiTeamId" } } } }

Ensure /path/to/analytics_service points to the absolute directory containing your analytics service code.

For UMAMI_API_URL, substitute https://example.com with the correct endpoint for your Umami instance (self-hosted or Umami Cloud).
For UMAMI_USERNAME and UMAMI_PASSWORD, input your Umami access credentials.
For UMAMI_TEAM_ID, specify the identifier of the team scope for analysis.
Initiating Claude Desktop Connection

Upon launching Claude Desktop, the application will automatically attempt to bootstrap the analytics_service MCP node. Allow a brief period (a few minutes) for initial server startup and dependency installation. Successful connection is signaled by the appearance of 10 available MCP utilities, indicated by a small wrench icon alongside the numeral 10 in the lower-right quadrant of the chat interface.

Crucially, it is highly advisable to enable the "Analysis tool" within Claude Desktop's Feature Preview settings. This feature unlocks Claude's capacity to render data visualizations and construct dashboards directly from the analyzed metrics. Access this by navigating to the "Feature Preview" tab on the left panel and activating the "Analysis tool." LaTeX Rendering can be activated in the same configuration area.

Operational Guidelines

Initial Steps

The most straightforward starting point is utilizing the server's pre-packaged Dashboard Generation Workflow. To invoke this, click the "Attach from MCP" button located at the bottom-left of the chat pane, subsequently selecting "choose implementation" and finally choosing the "Dashboard Generation Workflow."

This workflow prompts the user for three critical inputs: 1. The registered name of the website subject to analysis. 2. The desired temporal boundaries (start and end dates). 3. The established timezone of the website property.

Once these parameters are furnished, the server will output a plain text document detailing the necessary instructions for Claude to construct the dashboard visualization suite. After this output appears, press Enter in the chat input. Claude will then proceed with the dashboard construction. Subsequent inputs can direct Claude to iterate on or append new visualizations to the existing display.

Conversational Interface Usage

For more granular control and bespoke analytical requests, interact with Claude directly using natural language specifications. Articulate the specific data subsets you wish to examine or the visualizations you require. Furthermore, you can initiate deep dives into complex user sequences to isolate friction points, and integrate visual context via page screenshots.

The appropriate utilities required to fulfill the directive will be autonomously invoked by Claude. State your needs in plain language, and Claude will manage the tool orchestration. To review the complete inventory of accessible tools, query Claude to list them, or inspect the wrench icon in the bottom-right corner.

Custom Prompt Definition

You possess the capability to define proprietary workflows via custom prompts for frequently recurring operational sequences. This requires two steps:

Define Prompt Structure Establish a prompt definition containing:
name: A globally unique identifier for the prompt.
description: A lucid explanation of the prompt's objective.
arguments: A schema detailing required input parameters.

Template Structure: python @app.list_prompts() async def list_prompts(): return [ # ... existing prompts ... { "name": "Your Prompt Name", "description": "Your prompt description", "arguments": [ { "name": "Parameter Name 1", "description": "Parameter description", "required": True/False }, { "name": "Parameter Name 2", "description": "Parameter description", "required": True/False } ] } ]

Implement Prompt Logic Integrate the execution logic for your new prompt within the get_prompt() function in src/analytics_service/server.py: python @app.get_prompt() async def get_prompt(name: str, arguments: Any): # ... existing prompts ... if name == "Your Prompt Name": return { "messages": [ { "role": "user", "content": { "type": "text", "text": f"Your prompt template content referencing {arguments['Parameter Name']}" } } ] }

When structuring messages in your prompt definition, the role attribute is fundamental for defining the conversational turn: - Use "role": "user" to simulate input from the end-user or a query. - Use "role": "assistant" to represent Claude's generated output or instructions. - Use "role": "system" to establish overarching context or directive guidelines.

Messages must specify a content object detailing the type. Supported content types are: - "type": "text" - For conventional textual data. - "type": "resource" - For embedding external assets (logs, files, structured data). This requires a resource sub-object containing: - uri: A unique identifier for the resource. - text: The verbatim content of the resource. - mimeType: The content's media type (e.g., "text/plain", "text/x-python").

Although resources include content in the text field, utilizing the resource type offers distinct advantages: 1. Format Interpretation: The mimeType informs Claude how to correctly parse the payload (e.g., recognizing Python syntax vs. raw text). 2. Provenance Tracking: The uri field maintains a persistent pointer to the data's origin, which is valuable for auditing, tracking changes, or clarifying the context of the source material. 3. Data Structuring: This format allows consistent management of diverse content types while preserving necessary metadata.

Here is an illustration showcasing varied roles and content types: python "messages": [ { "role": "system", "content": { "type": "text", "text": "Examine the subsequent log entries and source code for anomalies." } }, { "role": "user", "content": { "type": "resource", "resource": { "uri": "logs://recent", "text": "[2024-03-14 15:32:11] ERROR: Connection timeout", "mimeType": "text/plain" } } }, { "role": "assistant", "content": { "type": "text", "text": "I detect a connection timeout error. Proceeding to inspect relevant source artifacts." } }, { "role": "user", "content": { "type": "resource", "resource": { "uri": "file:///code.py", "text": "def example():\n pass", "mimeType": "text/x-python" } } } ]

For the majority of straightforward prompts, relying on the text type within the user role suffices, granting Claude maximum latitude in its response generation. However, for intricate, multi-step orchestration, employing multiple messages with differentiated roles and content types enables a more rigorous conversation structure and enhances user control over the resulting execution flow.