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:

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_VERSION": "3", // Use "2" for Unomi V2, "3" for Unomi V3 (default)
        "UNOMI_USERNAME": "your-username", // Required for V2, fallback for V3
        "UNOMI_PASSWORD": "your-password", // Required for V2, fallback for V3
        "UNOMI_PROFILE_ID": "your-profile-id",
        "UNOMI_KEY": "your-unomi-key", // Required for V2 only
        "UNOMI_EMAIL": "[email protected]",
        "UNOMI_SOURCE_ID": "claude-desktop",
        "UNOMI_TENANT_ID": "your-tenant-id", // Required for V3
        "UNOMI_PUBLIC_KEY": "your-public-key", // Required for V3
        "UNOMI_PRIVATE_KEY": "your-private-key" // Required for V3
      }
    }
  }
}

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

Tools

    {
      "properties": {
        "firstName": "John",
        "age": 30,
        "isSubscribed": true,
        "oldProperty": null
      }
    }
    

    {
      "scope": "my-app",
      "name": "My Application",
      "description": "Scope for my application events"
    }
    

Consent Management Tools

    {
      "consentId": "marketing-consent",
      "status": "GRANTED",
      "typeIdentifier": "marketing",
      "scope": "claude-desktop",
      "metadata": {
        "source": "claude-desktop",
        "timestamp": "2024-01-15T10:30:00Z"
      }
    }
    

- get_consent - Get specific consent information for a profile
- Takes consentId as required parameter
- Returns consent details including status, timestamp, and metadata
- Uses your profile by default (from environment or email lookup)
- Example:

    {

      "consentId": "marketing-consent"

    }

    

- list_consents - List all consents for a profile with optional filtering
- Optional parameters:
- profileId: Profile ID to list consents for (uses your profile if not provided)
- status: Filter by consent status (GRANTED, DENIED, or REVOKED)
- scope: Filter by scope
- Returns filtered list of consents with metadata
- Example:

    {

      "status": "GRANTED",

      "scope": "claude-desktop"

    }

    

Scope Management

1. Default Scope:
- A default scope claude-desktop is used for all operations
- Created automatically when needed
- Used for profile updates and event tracking

2. Custom Scopes:
- Can be created using the create_scope tool
- Useful for separating different applications or contexts
- Must exist before using in profile operations

3. Automatic Scope Creation:
- The server checks if required scopes exist
- Creates them automatically if missing
- Uses meaningful defaults for scope metadata

> Note: While scopes are created automatically when needed, you can still create them manually with custom names and descriptions using the create_scope tool.

Apache Unomi V2/V3 Compatibility

This MCP server supports both Apache Unomi V2 and V3 with automatic version detection and appropriate authentication methods.

Version Detection

The server automatically detects the Unomi version based on the UNOMI_VERSION environment variable:
- UNOMI_VERSION=2 - Uses V2 authentication (system administrator)
- UNOMI_VERSION=3 - Uses V3 authentication (tenant-based) - Default

V2 vs V3 Authentication

V2 (Legacy):
- Uses system administrator authentication (karaf/karaf by default)
- All operations use the same authentication method
- Requires UNOMI_USERNAME, UNOMI_PASSWORD, and UNOMI_KEY

V3 (Multi-tenant):
- Uses tenant-based authentication with API keys
- Different authentication for different endpoint types:
- Public endpoints (/context.json): Uses X-Unomi-Api-Key header with public key
- Private endpoints (profiles, scopes): Uses tenant authentication (tenantId:privateKey)
- System operations: Falls back to system administrator authentication
- Requires UNOMI_TENANT_ID, UNOMI_PUBLIC_KEY, and UNOMI_PRIVATE_KEY

Migration from V2 to V3

1. Update environment variables:

   # Remove V2-specific variables

   # UNOMI_KEY (no longer needed)

   

   # Add V3-specific variables

   UNOMI_VERSION=3

   UNOMI_TENANT_ID=your-tenant-id

   UNOMI_PUBLIC_KEY=your-public-key

   UNOMI_PRIVATE_KEY=your-private-key

   

2. Benefits of V3:
- Complete data isolation between tenants
- Enhanced security with tenant-specific API keys
- Better scalability for multi-tenant deployments
- Improved compliance with data privacy regulations

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

2. Context Management:
- Store and retrieve user preferences
- Manage user consent preferences
- Track consent status and history

3. Consent Management:
- Update user consent status using Apache Unomi's Consent API
- Retrieve specific consent information
- List and filter consents by status and scope
- Automatic consent expiration handling (GDPR compliant)
- Support for GDPR and privacy compliance

4. Integration Features:
- Seamless Claude Desktop integration
- Automatic session management
- Scope-based context isolation

What You Can Do

Prerequisites

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 (if UNOMI_EMAIL is set):
- Searches for a profile with matching email
- If found, uses that profile's ID
- Useful for maintaining consistent profile across sessions

2. Fallback Profile ID:
- If email lookup fails or UNOMI_EMAIL is not set
- Uses the UNOMI_PROFILE_ID from environment
- Ensures a profile is always available

The response will indicate which method was used via the source field:
- "email_lookup": Profile found via email
- "environment": Using fallback profile ID

Unomi Server Configuration

1. Configure protected events in etc/org.apache.unomi.cluster.cfg:

   # Required for protected events like property updates

   org.apache.unomi.cluster.authorization.key=your-unomi-key

   

   # Required to allow Claude Desktop to access Unomi

   # Replace your-claude-desktop-ip with your actual IP

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

   

2. Ensure your Unomi server has CORS properly configured in etc/org.apache.unomi.cors.cfg:

   # Add your Claude Desktop origin if needed

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

   

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

   # Required for protected events like property updates

   org.apache.unomi.cluster.authorization.key=your-unomi-key

   

   # Required to allow Claude Desktop to access Unomi

   # Replace your-claude-desktop-ip with your actual IP

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

   

   # Add your Claude Desktop origin if needed

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

   

3. Restart Unomi server to apply changes

> Important: The Unomi key must match exactly between your server configuration and the UNOMI_KEY environment variable in Claude Desktop.

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, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

You can also tail the Claude Desktop logs to see MCP requests and responses:

```bash