Integrates with Apache Unomi for user profile management and context storage, enabling Claude to maintain user context through Apache Unomi's profile management system
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
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 variablesUses UNOMI_PROFILE_ID from environment or email lookup
Automatically generates a session ID based on the current date
Optional parameters:
requireSegments: Include segment information
requireScores: Include scoring information
update_my_profile
- Update properties of your profileUses UNOMI_PROFILE_ID from environment or email lookup
Takes a properties object with key-value pairs to update
Supports string, number, boolean, and null values
Example:
{ "properties": { "firstName": "John", "age": 30, "isSubscribed": true, "oldProperty": null } }
get_profile
- Retrieve a specific profile by IDTakes profileId as required parameter
Returns full profile data from Unomi
search_profiles
- Search for profilesTakes query string and optional limit/offset parameters
Searches across firstName, lastName, and email fields
create_scope
- Create a new Unomi scopeTakes scope identifier and optional name/description
Required for event tracking and profile updates
Example:
{ "scope": "my-app", "name": "My Application", "description": "Scope for my application events" }
Scope Management
The server automatically manages scopes for you:
Default Scope:
A default scope
claude-desktop
is used for all operationsCreated automatically when needed
Used for profile updates and event tracking
Custom Scopes:
Can be created using the
create_scope
toolUseful for separating different applications or contexts
Must exist before using in profile operations
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.
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
User Recognition:
Identify users across conversations using email or profile ID
Maintain consistent user context between sessions
Automatically create and manage user profiles
Context Management:
Store and retrieve user preferences
Integration Features:
Seamless Claude Desktop integration
Automatic session management
Scope-based context isolation
What You Can Do
Have Claude remember user preferences across conversations
Store and retrieve user-specific information
Maintain consistent user context
Manage multiple users through email identification
Prerequisites
Running Apache Unomi server
Claude Desktop installation
Network access to Unomi server
Proper security configuration
Required environment variables
Configuration
Environment Variables
The server requires the following environment variables:
Profile Resolution
The server uses a two-step process to resolve the profile ID:
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
Fallback Profile ID:
If email lookup fails or
UNOMI_EMAIL
is not setUses the
UNOMI_PROFILE_ID
from environmentEnsures 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
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-ipEnsure 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:*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.
Configuration
Environment Variables
The server requires the following environment variables:
Profile Resolution
The server uses a two-step process to resolve the profile ID:
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
Fallback Profile ID:
If email lookup fails or
UNOMI_EMAIL
is not setUses the
UNOMI_PROFILE_ID
from environmentEnsures 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
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-ipEnsure 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:*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:
Build the server:
For development with auto-rebuild:
Debugging
Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:
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:
Session ID Format
When using get_my_profile
, the session ID is automatically generated using the format:
For example, if your profile ID is "user123" and today is March 15, 2024, the session ID would be:
Troubleshooting
Common Issues
Protected Events Failing
Verify Unomi key matches exactly in both configurations
Check IP address is correctly whitelisted
Ensure scope exists before updating properties
Verify CORS configuration if needed
Profile Not Found
Check if UNOMI_EMAIL is correctly set
Verify email format is valid
Ensure profile exists in Unomi
Check if fallback UNOMI_PROFILE_ID is valid
Session Issues
Remember sessions are date-based
Only one session per profile per day
Check session ID format matches
profileId-YYYYMMDD
Verify scope exists for session
Connection Problems
Verify Unomi server is running
Check network connectivity
Ensure UNOMI_BASE_URL is correct
Verify authentication credentials
Logs to Check
Claude Desktop Logs:
# MacOS ~/Library/Logs/Claude/mcp*.log # Windows %APPDATA%\Claude\mcp*.logUnomi Server Logs:
# Usually in $UNOMI_HOME/logs/karaf.log
Quick Fixes
Reset State:
# Stop Claude Desktop # Clear logs rm ~/Library/Logs/Claude/mcp*.log # Restart Claude DesktopVerify Configuration:
# Check Unomi connection curl -u username:password http://your-unomi-server:8181/cxs/cluster # Test scope exists curl -u username:password http://your-unomi-server:8181/cxs/scopes/claude-desktop
Claude Desktop Configuration options
Create or edit your Claude Desktop configuration:
MacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%/Claude/claude_desktop_config.json
Add the server configuration using NPX:
{ "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" } } } }
Note: Using NPX ensures you're always running the latest published version of the server.
Alternatively, if you want to use a specific version:
For development or local installations:
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Model Context Protocol server enabling Claude to maintain user context through Apache Unomi profile management.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server for Claude Desktop that provides structured memory management across chat sessions, allowing Claude to maintain context and build a knowledge base within project directories.Last updated -3
- -securityAlicense-qualityA Model Context Protocol server that enables Claude to interact with the ConnectWise Manage API to perform operations like retrieving, creating, updating, and deleting tickets, companies, contacts, and other entities.
- -securityFlicense-qualityA Model Context Protocol server that allows Claude to make API requests on your behalf, providing tools for testing various APIs including HTTP requests and OpenAI integrations without sharing your API keys in the chat.Last updated -
- AsecurityAlicenseAqualityA Model Context Protocol server that enables Claude to interact directly with Unity projects, providing tools for script creation, asset management, and project building.Last updated -156MIT License