Create a new BPMN diagram: blank, cloned from an existing diagram (cloneFrom), or imported from existing BPMN XML (xml or filePath). Returns a diagram ID that can be used with other tools. For an xml/filePath import, if the XML lacks diagram coordinates (DI), auto-layout is applied; use autoLayout to force or skip it. Warning: Forcing autoLayout: true on diagrams that already have DI coordinates may reposition elements and can affect boundary event placement — for diagrams with boundary events, subprocesses, or complex structures, prefer autoLayout: false (or omit it to use auto-detection). An xml/filePath import creates a fresh modeler with an empty undo/redo history; combine with export_bpmn filePath to implement an open→edit→save workflow. Use draftMode: true to suppress lint feedback during incremental construction.

Add one or more elements (tasks, gateways, events, etc.) to a BPMN diagram; a single element is an array of one. With connect "chain" (default) each element is connected to the previous one by a sequence flow (afterElementId attaches the first one after an existing element) and the diagram is laid out; with connect "none" they are only added, each placed right of the previous one. Chains containing a gateway are not auto-connected past it — wire branches with connect_bpmn_elements. An entry that sets its own anchor or position (hostElementId, flowId, fromElementId + toLaneId, copyFrom, afterElementId, x/y) is placed there instead of being chained, and then auto-layout is off unless autoLayout is true. Supports boundary events via hostElementId, inserting into a flow via flowId, and cross-lane handoff via fromElementId + toLaneId. Subprocesses are expanded by default (isExpanded=false for collapsed). Generates descriptive element IDs when a name is provided (e.g. UserTask_EnterName). See bpmn://guides/modeling-elements for naming conventions, integration patterns, and event subprocess guidance.

Connect BPMN elements. Supports pair mode (sourceElementId + targetElementId), chain mode (elementIds array for sequential connections), or batch mode (connections array for arbitrary source/target pairs, e.g. a gateway's branches with per-branch conditions). Auto-detects connection type: SequenceFlow for normal flow, MessageFlow for cross-pool, Association for text annotations, and DataAssociation for data objects/stores. Supports optional condition expressions for gateway branches and isDefault flag for gateway default flows. To modify an existing connection's label or condition after creation, use set_bpmn_element_properties with the connection's ID. Also supports waypoint mode: provide connectionId + waypoints to set custom routing on an existing connection.

Remove one or more elements or connections from a BPMN diagram. Supports single deletion via elementId or bulk deletion via elementIds array.

Move, resize, or reassign an element to a lane. Any combination of x/y (absolute move), width/height (resize, top-left preserved), and laneId (auto-centered) — at least one required. For several elements at once, pass moves: [{ elementId, x?, y?, width?, height?, laneId? }] instead — validated up front, applied as one undo step.

Export a BPMN diagram as XML, SVG, PNG, an animated GIF/APNG/MP4/WebP, or a standalone interactive HTML embed, and write it to a file. By default, runs bpmnlint and blocks export if there are error-level lint issues. Set skipLint to true to bypass validation. Optionally scope to a subprocess or participant via elementId (xml/svg/both only). Use format 'both' to get XML and SVG in a single call. PNG/animated/HTML formats always write to filePath (required for those formats) rather than inlining. Animated formats render token-simulation driven by an optional TOML scenario (see the executable-Camunda-7 guide resource); omit scenario to use the diagram's own default. gif/apng/mp4/webp/html require optional dependencies (gifenc or ffmpeg for encoding, smol-toml for scenario parsing) — errors name the missing one. The exported text content is also returned in the response, unless it is large — beyond a size threshold, xml/svg/both return a bpmn://diagram/{id}/xml or /svg resource_link plus a short summary instead of the full text; pass inline: true to force full text regardless of size. Binary/HTML formats return a confirmation only.

List elements in a BPMN diagram with their types, names, positions, connections, and properties. Supports optional filters to search by name pattern, element type, or property value. When no filters are given, returns all elements — unless the diagram is large, in which case an unfiltered call returns a type-count summary plus a bpmn://diagram/{id}/elements resource_link instead (pass inline: true to force the full list). Pass elementIds to inspect specific elements in full detail (all properties, extension elements, connections, event definitions) instead — ignores the other filters, one or several elements per call.

Set BPMN or Camunda extension properties on an element. Supports standard properties (name, isExecutable, documentation, default, conditionExpression) and Camunda extensions with camunda: prefix (e.g. camunda:assignee, camunda:class, camunda:type, camunda:topic). Also handles: scriptFormat/script on ScriptTask, camunda:connector, camunda:field, camunda:properties, camunda:retryTimeCycle, isExpanded on SubProcess, and cancelActivity on BoundaryEvent (false = non-interrupting). See bpmn://guides/element-properties for the full property catalog by element type. Supports optional elementType to replace the element type (e.g. bpmn:Task → bpmn:UserTask). Also accepts optional sub-objects for other concerns, settable together with properties in one call: inputOutput, formData, listeners, callActivityVariables, loop, eventDefinition. To update several elements in one call — e.g. setting camunda:assignee on every task in an executable process — pass updates: [{ elementId, properties, ... }] instead of the single-element elementId/properties/etc. fields. Every item is validated before any element is changed, and the whole batch applies as one undo step.

Remove a diagram from the in-memory store.

List all diagrams or get a detailed summary of one. When called without diagramId, lists all diagrams in memory with their IDs, names, and element counts. When diagramId is provided, returns a lightweight summary: process name, element counts by type, participant/lane names, named elements, and connectivity stats. When both diagramId and compareWith are provided, returns a structured diff between the two diagrams (additions, removals, and changes).

Validate a BPMN diagram using bpmnlint rules. Returns structured issues with rule names, severities, element IDs, documentation URLs, and fix suggestions (concrete MCP tool calls to resolve each issue). Uses bpmnlint:recommended by default with tuning for AI-generated diagrams. Supports custom config overrides.

Align or distribute selected elements. Supports two operations: (1) align — align elements along an axis (left, center, right, top, middle, bottom), requires at least 2 elements. Use compact=true to also redistribute with ~50px gaps. (2) distribute — evenly distribute elements horizontally or vertically using edge-to-edge spacing, requires at least 3 elements. Use gap for exact pixel spacing (recommended: 50). ⚠️ Warning: alignment: middle on a process with parallel branches collapses all branches onto a single Y row, causing horizontal overlaps. Use layout_bpmn_diagram instead to re-arrange the full diagram while preserving branch separation. If you must use alignment: middle, pass compact: true to detect and spread overlapping elements on the X axis afterwards.

Automatically arrange elements in a BPMN diagram using bpmn-auto-layout, producing a clean left-to-right layout with orthogonal connections and placed labels. Handles parallel branches, reconverging gateways, loops, boundary events, subprocesses, pools, lanes, message flows, and artifacts. Use this after structural changes (adding gateways, splitting flows) to automatically clean up the layout. The whole layout is a single undo step in bpmn_history. Use dryRun to preview changes before applying them. Use labelsOnly: true to only adjust label positions without moving elements. Partial layout: pass scopeElementId to re-layout only one participant/subprocess, or elementIds to re-layout only a set of sibling elements (e.g. a newly added branch); the rest of the diagram is left unchanged and connections crossing the boundary are re-routed. Elements positioned with move_bpmn_element are pinned and keep their position until the next full layout.

Undo or redo changes on a BPMN diagram. Uses the bpmn-js command stack to reverse or re-apply operations. Supports multiple steps. Note: layout operations (layout_bpmn_diagram) bypass the command stack for boundary event repositioning and the normaliseOrigin fallback — these specific changes cannot be undone.

Execute multiple BPMN operations in a single call, reducing round-trips. Operations run sequentially. By default, execution stops on first error (set stopOnError: false to continue). When stopOnError is true (default), all changes are rolled back on failure using the bpmn-js command stack. Nested batch calls are not allowed.

Create or update shared root-level bpmn:Message and bpmn:Signal definitions. These shared definitions can be referenced from multiple event definitions across the diagram via messageRef/signalRef in set_bpmn_element_properties's eventDefinition sub-object.

Create lanes (swimlanes) within a participant pool. Creates a bpmn:LaneSet with the specified lanes, dividing the pool height evenly (or using explicit heights). Lanes represent roles or departments within a single organization/process. Use lanes for role separation within one pool; use separate pools (participants) for separate organizations with message flows. Requires at least 2 lanes when defined manually. Alternatively, use distributeStrategy to auto-generate lanes: "by-type" groups elements into Human Tasks vs Automated Tasks lanes; "manual" uses elementIds in each lane definition to assign elements explicitly. Use assignments ([{ laneId, elementIds }]) to assign existing elements to existing lanes, or strategy (role-based | balance | minimize-crossings, with dryRun/validate) to redistribute elements across existing lanes. These forms are mutually exclusive. Use mergeFrom to convert a multi-pool collaboration into a single pool with lanes (elements are moved, message flows become sequence flows).

Create participant(s) (pools) in a BPMN diagram. Single pool: pass name. Wrap existing process: set wrapExisting=true. Multi-pool collaboration: pass participants array (min 2). Camunda 7: only one pool is executable; additional pools must be collapsed. For role separation within one organization, use lanes inside one pool — not multiple expanded pools.

Analyze lane organization in a BPMN diagram. Three modes: 'suggest' — analyze tasks and suggest optimal lane assignments based on roles (camunda:assignee/candidateGroups) or element types (human vs automated). Returns structured suggestions with lane names, coherence score, and reasoning. 'validate' — check if current lane assignment makes semantic sense by analyzing cross-lane flow frequency, zigzag patterns, single-element lanes, and overall coherence. Returns structured issues with fix suggestions. 'pool-vs-lanes' — evaluate whether a collaboration should use separate pools (different organizations/systems) or lanes (role separation within one organization). Returns recommendation with confidence and reasoning. Read-only; to assign or redistribute elements use create_bpmn_lanes.

List all process variables referenced in a BPMN diagram. Extracts variables from form fields, input/output parameter mappings, condition expressions, script result variables, loop characteristics, call activity variable mappings, and Camunda properties (assignee, candidateGroups, etc.). Returns each variable with its read/write access pattern and the elements that reference it — unless the diagram references a lot of variables, in which case it returns just the names plus a bpmn://diagram/{id}/variables resource_link (pass inline: true to force the full list).