A Model Context Protocol server enabling Claude to maintain user context through Apache Unomi profile management. 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 we
Add this skill
npx mdskills install sergehuber/inoyu-mcp-unomi-serverWell-documented MCP server enabling user context management through Apache Unomi with clear setup instructions
1# Inoyu Apache Unomi MCP Server23A Model Context Protocol server enabling Claude to maintain user context through Apache Unomi profile management.45> ⚠️ **Early Implementation Notice**6>7> This is an early implementation intended for demonstration purposes:8> - Not validated for production use9> - Subject to changes10> - Not (yet) officially supported11> - For learning and experimentation only1213## Current Scope1415This implementation provides:16- Profile lookup and creation using email17- Profile property management18- Basic session handling19- Scope management for context isolation2021Other Unomi features (events, segments, session properties, etc.) are not currently implemented. Community feedback welcome on future development priorities.2223## Demo2425Watch how the MCP server enables Claude to maintain context and manage user profiles:2627[](https://www.youtube.com/watch?v=YqPkUhBlcrs)2829## Installation3031To use with Claude Desktop, add the server config and environment variables:3233On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`34On Windows: `%APPDATA%/Claude/claude_desktop_config.json`3536```json37{38 "mcpServers": {39 "unomi-server": {40 "command": "npx",41 "args": ["@inoyu/mcp-unomi-server"],42 "env": {43 "UNOMI_BASE_URL": "http://your-unomi-server:8181",44 "UNOMI_VERSION": "3", // Use "2" for Unomi V2, "3" for Unomi V3 (default)45 "UNOMI_USERNAME": "your-username", // Required for V2, fallback for V346 "UNOMI_PASSWORD": "your-password", // Required for V2, fallback for V347 "UNOMI_PROFILE_ID": "your-profile-id",48 "UNOMI_KEY": "your-unomi-key", // Required for V2 only49 "UNOMI_EMAIL": "your-email@example.com",50 "UNOMI_SOURCE_ID": "claude-desktop",51 "UNOMI_TENANT_ID": "your-tenant-id", // Required for V352 "UNOMI_PUBLIC_KEY": "your-public-key", // Required for V353 "UNOMI_PRIVATE_KEY": "your-private-key" // Required for V354 }55 }56 }57}58```5960The `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.6162Make 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.6364## Features6566### Profile Access67- Email-based profile lookup with automatic creation68- Profile properties, segments, and scores access69- JSON format for all data exchange70- Automatic session management with date-based IDs7172### Tools73- `get_my_profile` - Get your profile using environment variables74 - Uses UNOMI_PROFILE_ID from environment or email lookup75 - Automatically generates a session ID based on the current date76 - Optional parameters:77 - requireSegments: Include segment information78 - requireScores: Include scoring information79- `update_my_profile` - Update properties of your profile80 - Uses UNOMI_PROFILE_ID from environment or email lookup81 - Takes a properties object with key-value pairs to update82 - Supports string, number, boolean, and null values83 - Example:84 ```json85 {86 "properties": {87 "firstName": "John",88 "age": 30,89 "isSubscribed": true,90 "oldProperty": null91 }92 }93 ```94- `get_profile` - Retrieve a specific profile by ID95 - Takes profileId as required parameter96 - Returns full profile data from Unomi97- `search_profiles` - Search for profiles98 - Takes query string and optional limit/offset parameters99 - Searches across firstName, lastName, and email fields100- `create_scope` - Create a new Unomi scope101 - Takes scope identifier and optional name/description102 - Required for event tracking and profile updates103 - Example:104 ```json105 {106 "scope": "my-app",107 "name": "My Application",108 "description": "Scope for my application events"109 }110 ```111- `get_tenant_info` - Get information about the current tenant (V3 only)112 - Returns tenant details, version information, and key status113 - Only available when using Unomi V3114 - No parameters required115116### Consent Management Tools117- `update_consent` - Update a user's consent status using the modifyConsent event118 - Uses the Apache Unomi Consent API as described in the [official documentation](https://unomi.apache.org/manual/latest/#_consent_api)119 - Required parameters:120 - consentId: Unique identifier for the consent121 - status: Consent status (GRANTED, DENIED, or REVOKED)122 - Optional parameters:123 - typeIdentifier: Type identifier of the consent124 - scope: Scope for the consent (defaults to claude-desktop)125 - metadata: Additional metadata for the consent126 - GDPR Compliance:127 - GRANTED consents expire after 1 year (GDPR recommendation)128 - DENIED/REVOKED consents expire immediately129 - Example:130 ```json131 {132 "consentId": "marketing-consent",133 "status": "GRANTED",134 "typeIdentifier": "marketing",135 "scope": "claude-desktop",136 "metadata": {137 "source": "claude-desktop",138 "timestamp": "2024-01-15T10:30:00Z"139 }140 }141 ```142143- `get_consent` - Get specific consent information for a profile144 - Takes consentId as required parameter145 - Returns consent details including status, timestamp, and metadata146 - Uses your profile by default (from environment or email lookup)147 - Example:148 ```json149 {150 "consentId": "marketing-consent"151 }152 ```153154- `list_consents` - List all consents for a profile with optional filtering155 - Optional parameters:156 - profileId: Profile ID to list consents for (uses your profile if not provided)157 - status: Filter by consent status (GRANTED, DENIED, or REVOKED)158 - scope: Filter by scope159 - Returns filtered list of consents with metadata160 - Example:161 ```json162 {163 "status": "GRANTED",164 "scope": "claude-desktop"165 }166 ```167168### Scope Management169The server automatically manages scopes for you:1701711. Default Scope:172 - A default scope `claude-desktop` is used for all operations173 - Created automatically when needed174 - Used for profile updates and event tracking1751762. Custom Scopes:177 - Can be created using the `create_scope` tool178 - Useful for separating different applications or contexts179 - Must exist before using in profile operations1801813. Automatic Scope Creation:182 - The server checks if required scopes exist183 - Creates them automatically if missing184 - Uses meaningful defaults for scope metadata185186> **Note**: While scopes are created automatically when needed, you can still create them manually with custom names and descriptions using the `create_scope` tool.187188## Apache Unomi V2/V3 Compatibility189190This MCP server supports both Apache Unomi V2 and V3 with automatic version detection and appropriate authentication methods.191192### Version Detection193194The server automatically detects the Unomi version based on the `UNOMI_VERSION` environment variable:195- `UNOMI_VERSION=2` - Uses V2 authentication (system administrator)196- `UNOMI_VERSION=3` - Uses V3 authentication (tenant-based) - **Default**197198### V2 vs V3 Authentication199200**V2 (Legacy):**201- Uses system administrator authentication (`karaf/karaf` by default)202- All operations use the same authentication method203- Requires `UNOMI_USERNAME`, `UNOMI_PASSWORD`, and `UNOMI_KEY`204205**V3 (Multi-tenant):**206- Uses tenant-based authentication with API keys207- Different authentication for different endpoint types:208 - **Public endpoints** (`/context.json`): Uses `X-Unomi-Api-Key` header with public key209 - **Private endpoints** (profiles, scopes): Uses tenant authentication (`tenantId:privateKey`)210 - **System operations**: Falls back to system administrator authentication211- Requires `UNOMI_TENANT_ID`, `UNOMI_PUBLIC_KEY`, and `UNOMI_PRIVATE_KEY`212213### Migration from V2 to V32142151. **Update environment variables:**216 ```bash217 # Remove V2-specific variables218 # UNOMI_KEY (no longer needed)219220 # Add V3-specific variables221 UNOMI_VERSION=3222 UNOMI_TENANT_ID=your-tenant-id223 UNOMI_PUBLIC_KEY=your-public-key224 UNOMI_PRIVATE_KEY=your-private-key225 ```2262272. **Benefits of V3:**228 - Complete data isolation between tenants229 - Enhanced security with tenant-specific API keys230 - Better scalability for multi-tenant deployments231 - Improved compliance with data privacy regulations232233## Overview234235This MCP server enables Claude to maintain context about users through Apache Unomi's profile management system. Here's what you can achieve with it:236237### Key Capabilities2381. **User Recognition**:239 - Identify users across conversations using email or profile ID240 - Maintain consistent user context between sessions241 - Automatically create and manage user profiles2422432. **Context Management**:244 - Store and retrieve user preferences245 - Manage user consent preferences246 - Track consent status and history2472483. **Consent Management**:249 - Update user consent status using Apache Unomi's Consent API250 - Retrieve specific consent information251 - List and filter consents by status and scope252 - Automatic consent expiration handling (GDPR compliant)253 - Support for GDPR and privacy compliance2542554. **Integration Features**:256 - Seamless Claude Desktop integration257 - Automatic session management258 - Scope-based context isolation259260### What You Can Do261- Have Claude remember user preferences across conversations262- Store and retrieve user-specific information263- Maintain consistent user context264- Manage multiple users through email identification265- Track and manage user consent preferences266- Comply with privacy regulations (GDPR, CCPA, etc.)267- Update consent status in real-time268- Query consent history and status269270### Prerequisites271- Running Apache Unomi server272- Claude Desktop installation273- Network access to Unomi server274- Proper security configuration275- Required environment variables276277## Configuration278279### Environment Variables280281The server requires the following environment variables:282283```bash284UNOMI_BASE_URL=http://your-unomi-server:8181285UNOMI_USERNAME=your-username286UNOMI_PASSWORD=your-password287UNOMI_PROFILE_ID=your-profile-id288UNOMI_SOURCE_ID=your-source-id289UNOMI_KEY=your-unomi-key290UNOMI_EMAIL=your-email291```292293### Profile Resolution294295The server uses a two-step process to resolve the profile ID:2962971. Email Lookup (if `UNOMI_EMAIL` is set):298 - Searches for a profile with matching email299 - If found, uses that profile's ID300 - Useful for maintaining consistent profile across sessions3013022. Fallback Profile ID:303 - If email lookup fails or `UNOMI_EMAIL` is not set304 - Uses the `UNOMI_PROFILE_ID` from environment305 - Ensures a profile is always available306307The response will indicate which method was used via the `source` field:308- `"email_lookup"`: Profile found via email309- `"environment"`: Using fallback profile ID310311### Unomi Server Configuration3123131. Configure protected events in `etc/org.apache.unomi.cluster.cfg`:314 ```properties315 # Required for protected events like property updates316 org.apache.unomi.cluster.authorization.key=your-unomi-key317318 # Required to allow Claude Desktop to access Unomi319 # Replace your-claude-desktop-ip with your actual IP320 org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip321 ```3223232. Ensure your Unomi server has CORS properly configured in `etc/org.apache.unomi.cors.cfg`:324 ```properties325 # Add your Claude Desktop origin if needed326 org.apache.unomi.cors.allowed.origins=http://localhost:*327 ```3283293. Restart Unomi server to apply changes330331> **Important**: The Unomi key must match exactly between your server configuration and the UNOMI_KEY environment variable in Claude Desktop.332333## Configuration334335### Environment Variables336337The server requires the following environment variables:338339```bash340UNOMI_BASE_URL=http://your-unomi-server:8181341UNOMI_USERNAME=your-username342UNOMI_PASSWORD=your-password343UNOMI_PROFILE_ID=your-profile-id344UNOMI_SOURCE_ID=your-source-id345UNOMI_KEY=your-unomi-key346UNOMI_EMAIL=your-email347```348349### Profile Resolution350351The server uses a two-step process to resolve the profile ID:3523531. Email Lookup (if `UNOMI_EMAIL` is set):354 - Searches for a profile with matching email355 - If found, uses that profile's ID356 - Useful for maintaining consistent profile across sessions3573582. Fallback Profile ID:359 - If email lookup fails or `UNOMI_EMAIL` is not set360 - Uses the `UNOMI_PROFILE_ID` from environment361 - Ensures a profile is always available362363The response will indicate which method was used via the `source` field:364- `"email_lookup"`: Profile found via email365- `"environment"`: Using fallback profile ID366367### Unomi Server Configuration3683691. Configure protected events in `etc/org.apache.unomi.cluster.cfg`:370 ```properties371 # Required for protected events like property updates372 org.apache.unomi.cluster.authorization.key=your-unomi-key373374 # Required to allow Claude Desktop to access Unomi375 # Replace your-claude-desktop-ip with your actual IP376 org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip377 ```3783792. Ensure your Unomi server has CORS properly configured in `etc/org.apache.unomi.cors.cfg`:380 ```properties381 # Add your Claude Desktop origin if needed382 org.apache.unomi.cors.allowed.origins=http://localhost:*383 ```3843853. Restart Unomi server to apply changes386387> **Important**: The Unomi key must match exactly between your server configuration and the UNOMI_KEY environment variable in Claude Desktop.388389## Development390391Install dependencies:392```bash393npm install394```395396Build the server:397```bash398npm run build399```400401For development with auto-rebuild:402```bash403npm run watch404```405406### Debugging407408Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:409410```bash411npm run inspector412```413414The Inspector will provide a URL to access debugging tools in your browser.415416You can also tail the Claude Desktop logs to see MCP requests and responses:417418```bash419# Follow logs in real-time420tail -n 20 -f ~/Library/Logs/Claude/mcp*.log421```422423### Session ID Format424When using `get_my_profile`, the session ID is automatically generated using the format:425```426[profileId]-YYYYMMDD427```428For example, if your profile ID is "user123" and today is March 15, 2024, the session ID would be:429```430user123-20240315431```432433## Troubleshooting434435### Common Issues4364371. **Protected Events Failing**438 - Verify Unomi key matches exactly in both configurations439 - Check IP address is correctly whitelisted440 - Ensure scope exists before updating properties441 - Verify CORS configuration if needed4424432. **Profile Not Found**444 - Check if UNOMI_EMAIL is correctly set445 - Verify email format is valid446 - Ensure profile exists in Unomi447 - Check if fallback UNOMI_PROFILE_ID is valid4484493. **Session Issues**450 - Remember sessions are date-based451 - Only one session per profile per day452 - Check session ID format matches `profileId-YYYYMMDD`453 - Verify scope exists for session4544554. **Connection Problems**456 - Verify Unomi server is running457 - Check network connectivity458 - Ensure UNOMI_BASE_URL is correct459 - Verify authentication credentials460461### Logs to Check4624631. **Claude Desktop Logs**:464 ```bash465 # MacOS466 ~/Library/Logs/Claude/mcp*.log467468 # Windows469 %APPDATA%\Claude\mcp*.log470 ```4714722. **Unomi Server Logs**:473 ```bash474 # Usually in475 $UNOMI_HOME/logs/karaf.log476 ```477478### Quick Fixes4794801. **Reset State**:481 ```bash482 # Stop Claude Desktop483 # Clear logs484 rm ~/Library/Logs/Claude/mcp*.log485 # Restart Claude Desktop486 ```4874882. **Verify Configuration**:489 ```bash490 # Check Unomi connection491 curl -u username:password http://your-unomi-server:8181/cxs/cluster492493 # Test scope exists494 curl -u username:password http://your-unomi-server:8181/cxs/scopes/claude-desktop495 ```496497### Claude Desktop Configuration options4984991. Create or edit your Claude Desktop configuration:500 - MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`501 - Windows: `%APPDATA%/Claude/claude_desktop_config.json`5025032. Add the server configuration using NPX:504 ```json505 {506 "mcpServers": {507 "unomi-server": {508 "command": "npx",509 "args": ["@inoyu/mcp-unomi-server"],510 "env": {511 "UNOMI_BASE_URL": "http://your-unomi-server:8181",512 "UNOMI_USERNAME": "your-username",513 "UNOMI_PASSWORD": "your-password",514 "UNOMI_PROFILE_ID": "your-profile-id",515 "UNOMI_KEY": "your-unomi-key",516 "UNOMI_EMAIL": "your-email@example.com",517 "UNOMI_SOURCE_ID": "claude-desktop"518 }519 }520 }521 }522 ```523524> **Note**: Using NPX ensures you're always running the latest published version of the server.525526Alternatively, if you want to use a specific version:527```json528{529 "mcpServers": {530 "unomi-server": {531 "command": "npx",532 "args": ["@inoyu/mcp-unomi-server@0.1.0"],533 "env": {534 // ... environment variables ...535 }536 }537 }538}539```540541For development or local installations:542```json543{544 "mcpServers": {545 "unomi-server": {546 "command": "node",547 "args": ["/path/to/local/mcp-unomi-server/build/index.js"],548 "env": {549 // ... environment variables ...550 }551 }552 }553}554```555556
Full transparency — inspect the skill content before installing.