Apache Unomi Profile Manager MCP Server

Customer Data PlatformsJavaScript

Connect Claude to Apache Unomi CDP for persistent user profile management

Available Tools

get_my_profile

Retrieves your profile using environment variables. Automatically looks up by email or uses UNOMI_PROFILE_ID, and generates a session ID based on the current date.

requireSegmentsrequireScores

update_my_profile

Updates properties of your profile. Takes a properties object with key-value pairs to update. Supports string, number, boolean, and null values.

properties

get_profile

Retrieves a specific profile by ID. Returns full profile data from Unomi.

profileId

search_profiles

Searches for profiles across firstName, lastName, and email fields.

querylimitoffset

create_scope

Creates a new Unomi scope for event tracking and profile updates.

scopenamedescription

The Apache Unomi Profile Manager enables Claude to maintain persistent user context through Apache Unomi's customer data platform. This integration allows Claude to remember user preferences, profile information, and context across conversations by leveraging Unomi's powerful profile management capabilities. With this tool, Claude can identify users by email, retrieve and update their profile properties, and maintain consistent context between sessions. The implementation supports profile lookup and creation, property management, basic session handling, and scope management for context isolation.

Overview

The Apache Unomi Profile Manager connects Claude to Apache Unomi, an open-source Customer Data Platform (CDP), allowing Claude to maintain persistent user context across conversations. This integration enables personalized interactions by giving Claude access to user profiles, preferences, and historical data.

Prerequisites

Before using this tool, you'll need:

A running Apache Unomi server
Claude Desktop installed
Network access from Claude Desktop to your Unomi server
Basic understanding of Apache Unomi concepts

Installation

To use the Apache Unomi Profile Manager with Claude Desktop:

Install the package via npm:
```
npm install @inoyu/mcp-unomi-server
```
Configure Claude Desktop by editing the configuration file:
- On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- On Windows: %APPDATA%/Claude/claude_desktop_config.json

Add the server configuration to the mcpServers section:

{
  "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": "your-email@example.com",
        "UNOMI_SOURCE_ID": "claude-desktop"
      }
    }
  }
}

Replace the placeholder values in the env section with your actual Unomi server details:
- UNOMI_BASE_URL: URL of your Unomi server (default port is 8181)
- UNOMI_USERNAME: Unomi admin username (default is "karaf")
- UNOMI_PASSWORD: Unomi admin password (default is "karaf")
- UNOMI_PROFILE_ID: Fallback profile ID if email lookup fails
- UNOMI_KEY: Unomi authorization key (default is "670c26d1cc413346c3b2fd9ce65dab41")
- UNOMI_EMAIL: Email address for profile lookup
- UNOMI_SOURCE_ID: Source identifier for Unomi events (e.g., "claude-desktop")
Restart Claude Desktop after updating the configuration

Unomi Server Configuration

Ensure your Unomi server is properly configured:

Edit etc/org.apache.unomi.cluster.cfg to set the authorization key and allow Claude Desktop's IP:

org.apache.unomi.cluster.authorization.key=your-unomi-key
org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip

Configure CORS in etc/org.apache.unomi.cors.cfg if needed:

org.apache.unomi.cors.allowed.origins=http://localhost:*

Restart your Unomi server to apply changes

Usage

Once configured, Claude can access and manage user profiles through the available tools. The integration automatically handles:

Profile lookup using email with fallback to environment variable
Session management with date-based IDs
Scope creation and management
Profile property updates

You can ask Claude to:

Retrieve your profile information
Update your profile properties
Search for specific profiles
Create new scopes for context isolation

Limitations

This is an early implementation with some limitations:

Not all Unomi features are implemented (events, segments, etc.)
Not validated for production use
Subject to changes as the implementation matures
Primarily intended for demonstration and learning purposes

Troubleshooting

If you encounter issues:

Check that your Unomi server is running and accessible
Verify the environment variables are correctly set
Ensure your Unomi server has the correct authorization key
Check that your IP is allowed in the Unomi configuration
Restart Claude Desktop after making configuration changes