Telemetry Bridge for Mixpanel Integration

This repository hosts a specialized Model Context Protocol (MCP) service endpoint dedicated to interfacing generative AI assistants (such as Claude) with the robust event tracking capabilities of the Mixpanel analytics platform.

Version Note (v2.0.1+): For enhanced clarity and to prevent naming conflicts within the MCP ecosystem, all exposed functions now bear the mixpanel_ prefix.

Core Functionality Overview

• Capture and log arbitrary, user-defined occurrences.
• Register screen transitions, including navigational context (referrers).
• Formalize the tracking of new user acquisition events and the initialization of user entities.
• Modify and enrich existing user attribute sets.
• Offers frictionless interoperability with clients supporting the MCP specification, including Claude Desktop.

---

Implementation Guide

Prerequisites

• Runtime Environment: Node.js, version 16 or later.
• Access Key: A valid Mixpanel Project Token (obtainable via sign-up at Mixpanel).

Deployment Methods

Recommended: Global NPM Installation

bash

Install utility globally

npm install -g mixpanel-mcp-server

Execute immediately using npx, providing the required token

npx mixpanel-mcp-server --token YOUR_MIXPANEL_TOKEN

Source Code Integration

bash

Clone the source repository

git clone https://github.com/yourusername/mixpanel-mcp-server.git cd mixpanel-mcp-server

Resolve dependencies

npm install

Launch the service

node index.js --token YOUR_MIXPANEL_TOKEN

Initiation Procedure (Claude Desktop)

To enable AI analysis of user journeys within Claude Desktop:

1. Ensure the Claude Desktop application is installed on your operating system (download link).

2. Locate or generate the Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %AppData%\Claude\claude_desktop_config.json

3. Inject the Mixpanel bridge configuration under the mcpServers section:

{ "mcpServers": { "mixpanel-data-pipe": { "command": "npx", "args": [ "-y", "mixpanel-mcp-server", "--token", "YOUR_MIXPANEL_TOKEN" ] } } }

1. Restart the Claude Desktop client. Analytics tracking capabilities are now active.

Operational Details

Interacting via Claude Desktop

Once configured, users can prompt Claude to interface with Mixpanel. Examples:

• "Log a custom data point named 'config_saved' for the entity identified as 'user123' via the analytics bridge."
• "Report a screen transition event for the application's main dashboard in Mixpanel."
• "Register John Smith for service, using the email john@example.com."
• "Synchronize the current feature set for client 'user123' within their Mixpanel record."

The AI model will autonomously select and invoke the required Mixpanel tool.

Interfacing with External MCP Clients

This service adheres to the standard Model Context Protocol, enabling connectivity with any compliant client:

1. Start the telemetry service instance (see Deployment Methods).
2. The external client should establish a connection utilizing the standard input/output transport mechanism (stdio).
3. The client can then perform service discovery to locate and utilize the functions: mixpanel_track_event, mixpanel_track_pageview, mixpanel_track_signup, and mixpanel_set_user_profile.

Function Reference

The following analytical operations are exposed by the service:

mixpanel_track_event

Logs a bespoke, named occurrence within the platform.

Arguments: * event_name (String, Mandatory): The semantic identifier for the occurrence. * distinct_id (String, Optional): The unique identifier for the subject. Defaults to 'anonymous'. * properties (Object, Optional): Supplementary data key-value pairs associated with the event.

Payload Example:

{ "event_name": "interaction_complete", "distinct_id": "user123", "properties": { "element_id": "checkout_button", "context_path": "/payment" } }

mixpanel_track_pageview

Records a navigation event for a specific interface view.

Arguments: * page_name (String, Mandatory): The descriptive label for the viewed screen. * distinct_id (String, Optional): The subject's identifier. Defaults to 'anonymous'. * referrer (String, Optional): The preceding source URL or page.

Payload Example:

{ "page_name": "dashboard_summary", "distinct_id": "user123", "referrer": "login_success_page" }

mixpanel_track_signup

Tracks the successful acquisition of a new user and establishes their initial record.

Arguments: * user_name (String, Mandatory): The individual's complete nominal identifier. * email (String, Mandatory): The associated electronic mail address. * plan (String, Optional): The initial service tier subscribed to. Defaults to 'free'.

Payload Example:

{ "user_name": "Alice Smith", "email": "alice@corp.com", "plan": "professional" }

mixpanel_set_user_profile

Updates or synchronizes descriptive attributes associated with an established user entity.

Arguments: * distinct_id (String, Mandatory): The subject identifier. * properties (Object, Mandatory): The attributes to be set or overwritten.

Payload Example:

{ "distinct_id": "user123", "properties": { "$name": "Alice Smith", "$email": "alice@corp.com", "organization_size": 50, "is_admin": true } }

Practical Interaction Scenarios

Example: Tracking an Interaction

User Prompt: "When the application finalizes a configuration update, please use the analytics bridge to log an event named 'settings_saved' for the active user ID."

AI Response Snippet: [Invokes mixpanel_track_event]

Example: Onboarding a New Client

User Prompt: "A new user, Bob Johnson, registered using bob@firm.net and selected the highest-tier subscription immediately."

AI Response Snippet: [Invokes mixpanel_track_signup]

Debugging and Maintenance

Resolving Common Errors

1. Service Fails to Bootstrap: Confirm the presence and correctness of the Mixpanel token argument. Verify Node.js environment integrity.
2. Client Discovery Failure: Double-check the JSON syntax and pathing within claude_desktop_config.json. Ensure a full restart of the host application follows configuration modifications.
3. Data Lacking in Mixpanel: Validate the token credentials against the Mixpanel project dashboard. Allow for typical data ingestion latency.

Verbose Logging Activation

For enhanced diagnostic output during runtime:

bash npx mixpanel-mcp-server --token YOUR_MIXPANEL_TOKEN --debug

Security Considerations

• Token Exposure: The API token resides in the local client configuration file; secure this file appropriately.
• Production Security: For high-volume or production contexts, leverage environment variables rather than hardcoding tokens.
• Abuse Prevention: This bridge currently lacks integrated throughput control; implement external rate limiting if deploying without a protective proxy.
• Data Compliance: All transmitted data is subject to Mixpanel's established privacy protocols; review these policies regarding sensitive information handling.

Contribution Guidelines

We welcome enhancements and bug fixes. To contribute:

1. Fork the repository.
2. Establish a new branch for your feature (git checkout -b feature/my-enhancement).
3. Commit modifications clearly.
4. Submit a Pull Request against the main branch.

Licensing

This software is distributed under the terms of the MIT License (refer to the accompanying LICENSE file).