@deitum/camunda-mcp

An MCP server for Camunda 7: BPMN and DMN definitions, running instances, variables, user tasks, incidents, history, DMN evaluation — and, behind a flag, the operations that change the engine.

It talks to the engine's REST API, so it works with a standalone distribution, a Spring Boot application with camunda-bpm-spring-boot-starter-rest, and an engine published behind a reverse proxy alike. Authentication covers the four schemes those deployments actually use: none, HTTP Basic, a ready-made token, and an OAuth2 / OIDC token endpoint — with the token sent either as Authorization: Bearer or in a cookie.

npx @deitum/camunda-mcp

It speaks MCP over stdio and is configured entirely through environment variables.

Setting it up in a client

Claude Desktop (claude_desktop_config.json), Cursor, Windsurf and anything else that reads the same shape:

{
  "mcpServers": {
    "camunda": {
      "command": "npx",
      "args": ["-y", "@deitum/camunda-mcp"],
      "env": {
        "CAMUNDA_BASE_URL": "http://localhost:8080/engine-rest",
        "CAMUNDA_USERNAME": "demo",
        "CAMUNDA_PASSWORD": "demo"
      }
    }
  }
}

Claude Code:

claude mcp add camunda \
  --env CAMUNDA_BASE_URL=http://localhost:8080/engine-rest \
  --env CAMUNDA_USERNAME=demo \
  --env CAMUNDA_PASSWORD=demo \
  -- npx -y @deitum/camunda-mcp

VS Code (.mcp.json / .vscode/mcp.json), where the password is prompted for rather than written down:

{
  "inputs": [
    {
      "id": "camunda-password",
      "type": "promptString",
      "description": "Camunda password",
      "password": true
    }
  ],
  "servers": {
    "camunda": {
      "command": "npx",
      "args": ["-y", "@deitum/camunda-mcp"],
      "env": {
        "CAMUNDA_BASE_URL": "http://localhost:8080/engine-rest",
        "CAMUNDA_USERNAME": "demo",
        "CAMUNDA_PASSWORD": "${input:camunda-password}"
      }
    }
  }
}

A variable left as a literal ${input:NAME} counts as unset, so a placeholder that was never filled in reads as a missing value rather than being sent to the engine as a username.

Configuration

| Variable | Required | Meaning | | ------------------------ | -------- | -------------------------------------------------------------------------- | | CAMUNDA_BASE_URL | yes | Engine REST root (which one?). | | CAMUNDA_AUTH | – | none | basic | bearer | oauth. Inferred when omitted. | | CAMUNDA_USERNAME | – | User, for Basic auth or the OAuth password grant. | | CAMUNDA_PASSWORD | – | Its password. | | CAMUNDA_TOKEN | – | A ready-made token to send as-is (bearer). | | CAMUNDA_TOKEN_URL | – | OAuth2 / OIDC token endpoint (oauth). | | CAMUNDA_CLIENT_ID | – | OAuth client. | | CAMUNDA_CLIENT_SECRET | – | Only for a confidential client. | | CAMUNDA_GRANT_TYPE | – | password | client_credentials. Inferred from whether a user is given. | | CAMUNDA_SCOPE | – | Scope to request, if the provider needs one. | | CAMUNDA_AUTH_TRANSPORT | – | header (default) | cookie — how the token reaches the engine. | | CAMUNDA_COOKIE_NAME | – | Cookie to put it in when the transport is cookie (default JWT). | | CAMUNDA_ALLOW_WRITE | – | true registers the tools that change the engine. Default off. | | CAMUNDA_SSL_VERIFY | – | false stops verifying TLS certificates (why). Default on. | | CAMUNDA_MAX_RESULTS | – | Default page size (default 20, hard cap 100). | | CAMUNDA_TIMEOUT_MS | – | Per-request budget (default 30000). |

The two flags read true/1/yes and false/0/no; anything else leaves the default in place, so a typo can only fail closed — writes off, certificates verified.

Authentication

Set only the variables your engine needs; the mode follows from them, and CAMUNDA_AUTH is there for the rare case where the guess is wrong.

None — a local distribution with the auth filter switched off:

CAMUNDA_BASE_URL=http://localhost:8080/engine-rest

HTTP Basic — what Camunda's own ProcessEngineAuthenticationFilter speaks, and what camunda-bpm-platform:run ships with:

CAMUNDA_USERNAME=demo
CAMUNDA_PASSWORD=demo

A ready-made token — one you already have from somewhere else:

CAMUNDA_TOKEN=eyJhbGciOi…

OAuth2 / OIDC — this server fetches tokens itself and renews them as they expire, sharing one grant across concurrent tool calls and using the refresh token when the provider issues one:

# password grant
CAMUNDA_TOKEN_URL=https://idp.example/realms/demo/protocol/openid-connect/token
CAMUNDA_CLIENT_ID=camunda-client
CAMUNDA_CLIENT_SECRET=…        # confidential clients only
CAMUNDA_USERNAME=user
CAMUNDA_PASSWORD=…

# client-credentials grant — drop the user, that is the whole difference
CAMUNDA_TOKEN_URL=https://idp.example/realms/demo/protocol/openid-connect/token
CAMUNDA_CLIENT_ID=camunda-service
CAMUNDA_CLIENT_SECRET=…

Credentials are all-or-nothing per mode: a half-filled set fails at startup, naming what is missing, rather than turning every tool call into the engine's login page.

Bearer header or cookie?

By default a token travels as Authorization: Bearer <token>, which is what a Camunda engine expects. Some deployments publish the engine behind a proxy or an OIDC filter that reads the token from a cookie and ignores the Authorization header entirely — for those:

CAMUNDA_AUTH_TRANSPORT=cookie
CAMUNDA_COOKIE_NAME=JWT        # the default; change it if the filter uses another name

When the transport is cookie no Authorization header is sent at all. The symptom of getting this wrong is a 302 to the identity provider while the same token works in the other position — the error message says exactly that, and which variable to flip.

Which base URL?

• standalone distribution or Spring Boot starter → https://host/engine-rest
• deployment where only the webapp is exposed → https://host/camunda/api/engine/engine/default

Both serve the same API. Getting it wrong is the common failure and does not look like one — the front-end that owns the wrong path tends to answer 200 text/html — so the server checks for that and says which URLs to try.

TLS

An internally hosted engine is often signed by a private root that Node does not ship, so the first call fails with SELF_SIGNED_CERT_IN_CHAIN while curl against the same URL works (it uses the system store). The error message says as much rather than repeating fetch failed.

Two ways out, in order of preference:

NODE_EXTRA_CA_CERTS=/path/to/internal-root.pem   # keeps verification, just teaches Node the root
CAMUNDA_SSL_VERIFY=false                         # verifies nothing at all

CAMUNDA_SSL_VERIFY=false sets NODE_TLS_REJECT_UNAUTHORIZED=0, which is process-wide: Node's fetch takes TLS settings from the process, not per connection, so it covers the token endpoint too and there is no way to scope it to the engine alone. It leaves the connection open to interception — use it against a development engine, and add the root certificate for anything else. The startup banner on stderr says TLS verification OFF while it is in effect.

Tools

Read-only, always registered:

| Tool | What it answers | | ---------------------------------------- | ------------------------------------------------------- | | camunda_list_decision_definitions | deployed DMN decisions (Cockpit's «Decisions») | | camunda_get_decision_dmn | the DMN XML — the decision table itself | | camunda_evaluate_decision | runs a decision against inputs, returns the output rows | | camunda_list_decision_instances | evaluation history with inputs/outputs | | camunda_list_process_definitions | deployed BPMN processes | | camunda_get_process_bpmn | the BPMN XML (source of activity ids) | | camunda_list_process_instances | running instances, by key or business key | | camunda_get_activity_instances | where an instance is sitting right now | | camunda_list_variables | an instance's variables, unwrapped | | camunda_list_tasks | open user tasks | | camunda_list_incidents | open incidents | | camunda_get_job_stacktrace | the exception behind a failed job | | camunda_list_history_process_instances | finished instances | | camunda_list_history_activities | one instance's audit trail | | camunda_list_deployments | deployments, newest first | | camunda_get_deployment_resource | a deployment's files, or one file's content | | camunda_get | escape hatch: any engine GET by path |

Registered only with CAMUNDA_ALLOW_WRITE=true: camunda_start_process_instance, camunda_complete_task, camunda_modify_process_instance, camunda_set_variables, camunda_send_message, camunda_set_job_retries, camunda_resolve_incident, camunda_delete_process_instance.

The write half is not registered rather than merely discouraged: a model cannot be told "do not touch" reliably, but it cannot call a tool it was never shown.

camunda_evaluate_decision is deliberately in the read half: it changes no engine state (only a history entry) and it is much of the reason to point this at an engine's decision tables.

Variables are passed as plain JSON ({"amount": 100}) and typed automatically; pass the engine's own envelope ({"amount": {"value": "100", "type": "String"}}) when you need an exact type.

Results are trimmed on the way back: list tools project each row down to the fields worth reading, maxResults is capped at 100, XML at 40 000 characters and any single result at 60 000 — an engine page of a few thousand rows would otherwise land in the model's context whole.

Troubleshooting

| Symptom | What it means | | --------------------------------------- | ------------------------------------------------------------------------------------------------ | | 302 to the identity provider | The token was not accepted in the position it was sent — try the other CAMUNDA_AUTH_TRANSPORT. | | returned HTML, not engine JSON | CAMUNDA_BASE_URL points at a front-end, not the engine REST root. | | SELF_SIGNED_CERT_IN_CHAIN | Node does not trust the chain; see TLS. | | Incomplete <mode> credentials | A half-filled set — the message names the missing variables. | | Engine rejected the credentials (401) | The engine understood the credentials and refused them. |

Checking a deployment by hand, which separates a bad URL from a bad token:

curl -s -u demo:demo "http://localhost:8080/engine-rest/decision-definition?maxResults=5"

A JSON array means the base URL and the credentials are both right. HTML means the base URL is wrong. A 302 to an identity provider means the credentials were not accepted in that position.

Using it as a library

The stdio binary is the point, but the server is exported too — for a custom transport or a test harness:

import { createCamundaServer, loadConfig } from '@deitum/camunda-mcp';

const server = createCamundaServer(loadConfig(process.env));
await server.connect(myTransport);

Development

npm install
npm run verify        # lint, format, types, tests, build, packaging
npm test              # vitest, no network
npm run inspector     # build, then drive it with the MCP inspector

Against a throwaway engine:

docker run --rm -p 8080:8080 camunda/camunda-bpm-platform:run-latest
CAMUNDA_BASE_URL=http://localhost:8080/engine-rest \
  CAMUNDA_USERNAME=demo CAMUNDA_PASSWORD=demo \
  npx @modelcontextprotocol/inspector node dist/cli.js

See CONTRIBUTING.md.

Licence

MIT.