@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.

Related MCP server: n8n MCP Server

Configuration

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). Either point NODE_EXTRA_CA_CERTS at the root certificate, or set NODE_TLS_REJECT_UNAUTHORIZED=0 for this process. The error message says as much rather than repeating fetch failed.

Tools

Read-only, always registered:

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

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.