Camunda7 Client

Docker Hub Docker Pulls Release CI MCP

Drive Camunda 7 / CIB Seven from any AI assistant — process operations and analytics over the Model Context Protocol.

One MCP server, two modules (operations + analytics), and a fleet of interactive MCP App widgets that render dashboards, BPMN diagrams and incident panels straight into the chat. Built on mcp-use.

Ask "why is the loan-approval process stalling?" — the assistant lists the running instances, opens the incident panel, reads the metrics, and offers to retry the failed jobs. No cockpit tab-hunting, no PromQL.

🐳 Pull the server image from Docker Hub →

What you get

• Conversational BPM operations — list and inspect process definitions, instances, user tasks, external tasks, incidents, jobs, deployments and history; start, modify, suspend, migrate, and resolve — exposed as camunda7_* tools.
• Process analytics — Prometheus-backed KPIs: performance, bottlenecks, failed instances, cluster / version / engine comparison, and a live engine-health snapshot, as analytics_* tools.
• Interactive widgets (MCP Apps) — cockpit dashboard, process & incident panels, BPMN viewer, heatmaps and history timeline rendered for the user while the model gets a compact summary.
• Multi-engine routing — talk to several engines at once (CIB Seven, Operaton and Camunda 7 mixed in one fleet) with a per-user default engine plus per-call overrides; analytics aggregate or compare across engines.
• Toolset scoping — narrow the surface to read-only, operations, or admin per deployment.
• Self-hostable — a single multi-arch (amd64/arm64) image on Docker Hub, plus a drop-in Micrometer metrics plugin for the engine.

Quick start

Pull the published server image and point an MCP client at it. You need a reachable CIB Seven / Camunda 7 engine (REST API) and — for the analytics module — a Prometheus instance.

docker run --rm -p 8400:8400 \
  -e CAMUNDA_BASE_URL=http://host.docker.internal:8410/engine-rest \
  -e CAMUNDA_AUTH_TYPE=basic \
  -e CAMUNDA_USERNAME=demo \
  -e CAMUNDA_PASSWORD=demo \
  -e PROMETHEUS_URL=http://host.docker.internal:9090 \
  docker.io/miragon/miragon-ai-server:latest

The server speaks the streamable-HTTP MCP transport on http://localhost:8400/mcp. Add it to your MCP host as an HTTP/streamable server — claude mcp add --transport http miragon-ai http://localhost:8400/mcp for Claude Code, a custom connector on your public URL for claude.ai / ChatGPT. Claude Desktop takes stdio servers only, so bridge it there:

{
  "mcpServers": {
    "miragon-ai": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8400/mcp", "--transport", "http-only"]
    }
  }
}

See How to use it for the full connection matrix and what to ask once connected.

Prefer to build the image yourself? No credentials needed — build it and run miragon-ai-server in place of the Docker Hub image above.

docker build -t miragon-ai-server .

Want the whole stack on your machine? The repo ships a Compose file with CIB Seven, the OTEL Collector, Prometheus and Grafana wired together — see playground/docker/ and Local development below.

How it works

┌─────────────────────────────────────────────────────┐
│            MCP Host (Claude, ChatGPT, ...)          │
│  ┌──────────────────────────────────────────────┐   │
│  │              miragon-ai-server               │   │
│  │  ┌─────────────────┐  ┌──────────────────┐   │   │
│  │  │ camunda7 module │  │ analytics module │   │   │
│  │  │  BPM ops tools  │  │  analytics tools │   │   │
│  │  │  + widgets      │  │  + dashboards    │   │   │
│  │  └────────┬────────┘  └────────┬─────────┘   │   │
│  └───────────┼─────────────────────┼────────────┘   │
└──────────────┼─────────────────────┼────────────────┘
               ▼                     ▼
    ┌────────────────────┐ ┌─────────────────────┐
    │  OpenAPI Client    │ │  Prometheus Client  │
    │  (hey-api/openapi) │ │  (PromQL, HTTP API) │
    └──────────┬─────────┘ └──────────┬──────────┘
               ▼                      ▼
    ┌────────────────────┐ ┌─────────────────────┐
    │   CIB Seven /      │ │   Prometheus        │
    │   Camunda 7 REST   │ │  (process metrics)  │
    └────────────────────┘ └──────────┬──────────┘
                                      ▲
                          ┌───────────┴───────────┐
                          │  OTEL Collector       │
                          │  ◄── engine metrics   │
                          └───────────────────────┘

Operations tools call the engine's REST API directly. Analytics tools query Prometheus, which is fed by the engine metrics plugin via the OpenTelemetry Collector — so analytics never touch the engine database and stay model-bounded (definition keys, activity ids, engine ids only — never instance ids or variable values).

Modules & packages

A pnpm + Turbo monorepo. The server composes the two modules and serves them as one MCP endpoint.

Path	Package	Role
apps/mcp-server-camunda7/	@miragon-ai/mcp-server-camunda7	The MCP host: composes modules, bundles widgets, serves HTTP on :8400
packages/connectors/camunda/camunda7-connector/	@miragon-ai/camunda7-connector	Camunda 7 operations tools, widget tools, and React widgets
packages/connectors/analytics/analytics-connector/	@miragon-ai/analytics-connector	Prometheus-backed analytics tools and dashboard widgets
packages/connectors/camunda/camunda7-client/	@miragon-ai/camunda7-client	Generated CIB Seven REST SDK + MCP-oriented Zod schemas
packages/connectors/analytics/analytics-client/	@miragon-ai/analytics-client	Prometheus client, PromQL query functions + metrics contract
packages/core/widget-shell/	@miragon-ai/widget-shell	Shared widget plumbing (adaptDataWidget, view builders)
engine-plugins/	io.miragon.mcp:cibseven-history-metrics	Kotlin Micrometer metrics plugin for CIB Seven (Java 21)
playground/	—	Demo env: CIB Seven showcase, Compose stack, Fly.io deploy
docs/	@miragon-ai/docs	VitePress documentation site

Tools

Camunda 7 module — camunda7_*

BPM operations across these domains (category): engines, process-definitions, process-instances, tasks, external-tasks, messages-signals, deployments, incidents, jobs, history, migrations. Highlights:

• Process definitions — list_process_definitions, get_process_definition_xml
• Process instances — start, list, get, delete, modify, set_*_suspension, get_activity_instance_tree, variables
• User & external tasks — list/get/claim/unclaim/complete, fetch_and_lock, complete_external_task, handle_external_task_failure
• Incidents & jobs — list_incidents, resolve_incident, format_incident_issue, list_jobs, set_job_retries
• History & migrations — query_historic_*, migration tools
• Widgets — show_cockpit_dashboard, show_process_list/detail, show_incidents_dashboard, show_bpmn_viewer, show_history_timeline, show_job_panel, …

Analytics module — analytics_*

Prometheus-backed analysis over PromQL: analyze_process_performance, compare_execution_periods, element_bottleneck, find_failed_instances, cluster_compare, version_compare, engine_landscape (the cross-engine overview: what runs where, load and job backlog per engine), engine_compare (one process definition on two engines), and engine_health (a live WIP / incidents / backlog / alerts snapshot). Widgets: show_dashboard, show_failure_dashboard, show_cluster_compare, show_version_compare, show_engine_landscape, show_engine_compare, show_bpmn_heatmap.

Across engines the tools report counts, never per-engine rates: engines host different process definitions, so an aggregated failure rate or duration describes that engine's process mix rather than the engine. engine_compare therefore requires a processDefinitionKey — engine_landscape lists the definitions deployed on more than one engine as its valid inputs.

Toolsets

Narrow the camunda7 surface per deployment via a suffix in MCP_ACTIVE_MODULES:

Toolset	Surface
camunda7:read-only	Queries only (list_*, get_*, query_*) plus engine selection — monitoring without writes
camunda7:operations	Read-only plus day-to-day writes (start instances, complete/claim tasks, variables, retries, messages, signals)
camunda7:admin	Everything, including delete/modify/suspend, deployments, migrations

Example: MCP_ACTIVE_MODULES=camunda7:read-only,analytics.

Configuration

The most common variables — see docs/operations.md for the full reference.

Variable	Default	Description
PORT	8400	HTTP port the MCP server listens on
MCP_ACTIVE_MODULES	all	Comma-separated modules (camunda7,analytics), each with an optional toolset suffix
MCP_OAUTH	—	JSON OAuth resource-server config (Keycloak / Auth0; the 1.x generic-OIDC/oidc-proxy modes were removed with mcp-use 2) protecting /mcp
CAMUNDA_BASE_URL	http://localhost:8410/engine-rest	Single-engine REST base URL
CAMUNDA_ENGINE_ID	default	Id of that engine — must match the engine's ENGINE_ID or its analytics stay empty
CAMUNDA_ENGINES_JSON / CAMUNDA_ENGINES_FILE	—	Register multiple engines (see Multi-engine)
CAMUNDA_COCKPIT_URL	derived	Cockpit web base for jump-out links
CAMUNDA_AUTH_TYPE	none	basic, bearer, passthrough, or none — fallback for engines without an auth
CAMUNDA_USERNAME / CAMUNDA_PASSWORD / CAMUNDA_TOKEN	—	Credentials for basic/bearer; passthrough forwards each caller's bearer token
PROMETHEUS_URL	http://localhost:9090	Prometheus HTTP API — the analytics data source

Multi-engine

The server can route to several engines — CIB Seven, Operaton and Camunda 7 mixed in one fleet. Tag each engine in its metrics plugin (ENGINE_ID), register them in the server (CAMUNDA_ENGINES_JSON / CAMUNDA_ENGINES_FILE — ENGINE_ID must match the registered id, or that engine's analytics come back empty), and the host discovers them via the camunda7_engine tool (list / select / current); select saves an engine as the caller's default (a per-user profile setting, so it needs MCP_OAUTH identity). Every operations tool also accepts a per-call engine override, which works without any identity. Analytics tools take an optional engine filter to aggregate or compare. Each engine entry may carry its own auth ({type, username?, password?, token?}); entries without one use the global CAMUNDA_* settings. Entries may also declare their vendor via flavor (cibseven | operaton | camunda7, default cibseven), which selects the engine's cockpit-link routes and display name.

Fleets that span several environments (each environment hosting some services with an engine) group their engines per environment: the cockpit landing becomes a two-stage selection (pick the environment first, then one of its engines), and the engine switcher, the settings page and camunda7_engine list group their engines by environment. Either write the engines JSON as a map keyed by environment id, or tag entries individually:

{
  "prod-eu": [{ "id": "prod-a", "baseUrl": "http://engine-a:8410/engine-rest" }],
  "prod-us": [{ "id": "prod-b", "baseUrl": "http://engine-b:8410/engine-rest" }]
}

Engine ids stay globally unique across environments — the id remains the ENGINE_ID metrics join key and the per-call engine selector; the environment is a grouping level only. Full walkthrough in docs/operations.md.

Engine metrics plugin

The analytics module needs camunda_* series in Prometheus. The Kotlin plugin in engine-plugins/ records them as Micrometer meters from inside the CIB Seven runtime — no engine-side database; export via Micrometer's OTLP registry (the playground default), an Actuator Prometheus scrape, or the OTEL Java agent's Micrometer bridge. It publishes to Maven Central as io.miragon.mcp:cibseven-history-metrics. See engine-plugins/README.md and the runnable playground/cibseven-example/.

Local development

Run the full stack — infra in Docker, the server from source with hot reload.

pnpm install --frozen-lockfile

docker compose -f playground/docker/docker-compose.yml up -d   # CIB Seven, OTEL, Prometheus, Grafana
cp .env.example .env                                 # dev defaults: engine on :8410, Prometheus on :8460
pnpm dev                                             # MCP server on :8400

pnpm dev also serves the mcp-use inspector at http://localhost:8400/mcp/inspector — call tools and render widgets by hand. The minimum bar for any change:

pnpm build && pnpm typecheck && pnpm test && pnpm lint
cd engine-plugins && ./gradlew build      # Kotlin: compile + unit + Konsist architecture tests

See docs/developer.md and CLAUDE.md for the architecture invariants and house patterns.

Documentation

• Architecture — one-page mental model of the server, modules and systems
• For Developers — clone, install, and run the stack locally
• Operations — deployment, environment, and observability
• Usage — connect an assistant and operate your processes

Build the site locally with pnpm docs:dev.

Releases

Releases are automated with release-please: semantic commits on main open a Release PR; merging it tags the repo and publishes the server image to Docker Hub and the engine plugin to Maven Central.

Contributing

Issues, pull requests and discussions are welcome on GitHub. Use semantic commit messages (they drive the release), and make sure pnpm build && pnpm typecheck && pnpm test && pnpm lint passes. The repo-specific skills under .claude/skills/ document the two main feature paths.

License

See LICENSE.