Inoyu MCP Server for Apache Unomi Profile Management

Overview

The Inoyu MCP Server for Apache Unomi Profile Management implements a Model Context Protocol (MCP) endpoint that lets you retrieve, update, and manage customer profiles stored in an Apache Unomi instance. It acts as a lightweight bridge between MCP-aware clients and Unomi’s REST APIs, exposing standardized MCP operations for reading and writing CDP (Customer Data Platform) profile data and storing associated files.

This server is useful when you need to integrate Unomi into MCP-compatible workflows, provide a unified API for profile operations, or attach file objects to profiles (e.g., consent documents, scanned IDs, or enrichment artifacts). It simplifies common profile tasks — lookups, merges, partial updates, and file storage — while delegating persistence to Unomi and file storage to a configured storage backend.

Features

• Exposes MCP-style endpoints to read and write Apache Unomi profiles
• CRUD operations on profiles via MCP JSON payloads
• File upload / download linked to profile records (files-storage)
• Configurable connection to Apache Unomi (URL, credentials, TLS)
• Pluggable storage path for profile-related files (local or mounted volume)
• Logging and basic error translation between MCP and Unomi responses
• Designed for use in CDP integration pipelines and privacy workflows

Installation / Configuration

Prerequisites:

• Running Apache Unomi instance reachable from the MCP server
• Java 11+ (if a JAR is included) or Docker (preferred for isolation)
• Optional: writable volume for files storage

1. Clone repository

git clone https://github.com/sergehuber/inoyu-mcp-unomi-server.git
cd inoyu-mcp-unomi-server

2. Build and run (examples)

• Using Docker (recommended)

# build image (if Dockerfile exists)
docker build -t inoyu-mcp-unomi-server:latest .

# run with environment variables and mounted storage
docker run -d \
  -e UNOMI_URL="http://unomi.example.local:8181" \
  -e UNOMI_USER="admin" \
  -e UNOMI_PASSWORD="secret" \
  -e MCP_PORT=8080 \
  -v /var/lib/inoyu/files:/opt/inoyu/files \
  --name inoyu-mcp \
  inoyu-mcp-unomi-server:latest

• Running locally (example with JAR)

# after building a jar (if provided)
java -jar target/inoyu-mcp-unomi-server.jar \
  --unomi.url=http://unomi.example.local:8181 \
  --unomi.user=admin \
  --unomi.password=secret \
  --mcp.port=8080 \
  --files.path=/tmp/inoyu-files

3. Example application config (application.yml / env variables)

unomi:
  url: "http://unomi.example.local:8181"
  user: "admin"
  password: "secret"
mcp:
  port: 8080
files:
  storagePath: "/opt/inoyu/files"

Configuration table

Available Resources

• Source code and issues: https://github.com/sergehuber/inoyu-mcp-unomi-server
• Apache Unomi docs: consult your Unomi instance docs for REST endpoints and authentication
• MCP (Model Context Protocol): use client implementations that speak MCP to interact with this server

API Examples

Retrieve a profile (by profileId)

curl -X GET "http://localhost:8080/mcp/profiles/12345" \
  -H "Accept: application/json"

Update or patch a profile (partial merge)

curl -X POST "http://localhost:8080/mcp/profiles/12345" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"email":"[email protected]"}, "mergeStrategy":"merge"}'

Upload a file and link to a profile

curl -X POST "http://localhost:8080/mcp/profiles/12345/files" \
  -F "file=@/path/to/id-scan.pdf" \
  -F "metadata={\"type\":\"id-scan\"};type=application/json"

Download a file

curl -X GET "http://localhost:8080/mcp/profiles/12345/files/filename.pdf" -o filename.pdf

Error responses from Unomi are normalized to MCP-style error payloads for easier client handling.

Use Cases

• Profile enrichment pipeline: receive model context requests from an ML enrichment service, fetch the Unomi profile, append enrichment results, and persist updates back to Unomi through the MCP server.
• Consent and privacy workflows: attach consent artifacts (signed PDFs) to a profile and retrieve them when processing subject access or deletion requests.
• Frontend client integration: expose a compact MCP-facing API to internal apps that should not call Unomi directly, centralizing authentication and request shaping.
• Batch reconciliation: a background job can call the MCP server to perform controlled profile merges, ensuring merge strategies are applied consistently and files are stored alongside profiles.

Notes for Developers

• Ensure your Unomi instance allows the operations you need (read/write) and that credentials or API keys provided to the MCP server have appropriate permissions.
• For production, run the server behind a reverse proxy or API gateway and secure connections with TLS.
• Back up the files storage path and consider using network-mounted storage for HA deployments.

If you run into issues or want to extend the server (e.g., add S3-backed file storage or custom merge strategies), refer to the repository for source code and submit issues or pull requests on GitHub.