Inoyu Apache Unomi MCP Server

A Model Context Protocol server enabling Claude to maintain user context through Apache Unomi profile management.

⚠️ Early Implementation Notice

This is an early implementation intended for demonstration purposes:

• Not validated for production use
• Subject to changes
• Not (yet) officially supported
• For learning and experimentation only

Current Scope

This implementation provides:

• Profile lookup and creation using email
• Profile property management
• Basic session handling
• Scope management for context isolation

Other Unomi features (events, segments, session properties, etc.) are not currently implemented. Community feedback welcome on future development priorities.

Demo

Watch how the MCP server enables Claude to maintain context and manage user profiles: Demo Video

Installation

To use with Claude Desktop, add the server config and environment variables:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "unomi-server": {
      "command": "npx",
      "args": ["@inoyu/mcp-unomi-server"],
      "env": {
        "UNOMI_BASE_URL": "http://your-unomi-server:8181",
        "UNOMI_USERNAME": "your-username",
        "UNOMI_PASSWORD": "your-password",
        "UNOMI_PROFILE_ID": "your-profile-id",
        "UNOMI_KEY": "your-unomi-key",
        "UNOMI_EMAIL": "[email protected]",
        "UNOMI_SOURCE_ID": "claude-desktop"
      }
    }
  }
}

The env section in the configuration allows you to set the required environment variables for the server. Replace the values with your actual Unomi server details. Make sure to restart Claude Desktop after updating the configuration. You can then click on the tools icon on the lower right of the chat window to make sure it has found all the tools provided by this server.

Features# Profile Access

• Email-based profile lookup with automatic creation
• Profile properties, segments, and scores access
• JSON format for all data exchange
• Automatic session management with date-based IDs

Tools

• get_my_profile: Get your profile using environment variables
• update_my_profile: Update properties of your profile
• get_profile: Retrieve a specific profile by ID
• search_profiles: Search for profiles
• create_scope: Create a new Unomi scope

Scope Management

The server automatically manages scopes for you:

1. Default Scope: A default scope claude-desktop is used for all operations.
2. Custom Scopes: Can be created using the create_scope tool.
3. Automatic Scope Creation: The server checks if required scopes exist and creates them automatically if missing.

Overview

This MCP server enables Claude to maintain context about users through Apache Unomi's profile management system. Here's what you can achieve with it:

Key Capabilities

1. User Recognition: Identify users across conversations using email or profile ID.
2. Context Management: Store and retrieve user preferences.
3. Integration Features: Seamless Claude Desktop integration.

Prerequisites

• Running Apache Unomi server
• Claude Desktop installation
• Network access to Unomi server
• Proper security configuration

Configuration# Environment Variables

The server requires the following environment variables:

UNOMI_BASE_URL=http://your-unomi-server:8181
UNOMI_USERNAME=your-username
UNOMI_PASSWORD=your-password
UNOMI_PROFILE_ID=your-profile-id
UNOMI_SOURCE_ID=your-source-id
UNOMI_KEY=your-unomi-key
UNOMI_EMAIL=your-email

Profile Resolution

The server uses a two-step process to resolve the profile ID:

1. Email Lookup
2. Fallback Profile ID

Unomi Server Configuration

1. Configure protected events in etc/org.apache.unomi.cluster.cfg.
2. Ensure your Unomi server has CORS properly configured in etc/org.apache.unomi.cors.cfg.
3. Restart Unomi server to apply changes.

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector.

Troubleshooting

Common issues include protected events failing, profile not found, session issues, and connection problems. Check logs for more details.