Skip to main content
Glama

MCP-BPMN Server

A Model Context Protocol (MCP) server for a tested BPMN 2.0 authoring subset, including Mermaid conversion, local persistence, layout, validation, and XML or SVG export.

🎯 Overview

MCP-BPMN provides a stateful interface for AI assistants to work with one business process diagram at a time. It authors well-formed BPMN 2.0 XML for the constructs listed below; it is not a complete BPMN 2.0 editor, execution engine, or deployment client. Portable BPMN core is the default authoring contract, with an opt-in typed Camunda 7 profile documented in ADR 0001.

Key Features

  • Focused BPMN authoring: Supported events, activities, gateways, data objects, annotations, pools, top-level lanes, sequence flows, and associations

  • Mermaid conversion: Bootstrap diagrams from the documented flowchart subset

  • Horizontal auto-layout: Deterministic process and collaboration placement

  • Local persistence: Atomically save and reopen diagrams in a configured directory

  • XML/SVG export and rendered artifacts: XML is generated in-process; SVG export and managed SVG/PNG artifacts are rendered through Puppeteer and bpmn-js

  • Portable and Camunda 7 profiles: Vendor-free output by default, with three typed Camunda 7 user-task fields when explicitly selected

Related MCP server: MCP-GLSP

🚀 Quick Start

Requirements

  • Node.js 22.12.0 or newer

  • npm with lockfile support; make is additionally required for the Codex/Claude installer

  • macOS, Linux, or WSL2 with Linux-native Node.js, npm, and agent clients

  • Chrome or Chromium for export({ format: "svg" }), save_svg, and save_png; the normal Puppeteer install downloads a compatible browser

XML authoring, validation, layout, persistence, and XML export do not launch a browser. SVG export and managed SVG/PNG artifact rendering do. Rendering is headless, limited to one concurrent render per server instance, and has a twenty-second timeout.

Browser download

npm ci in this checkout runs Puppeteer's install step, which downloads Chrome for Testing and the headless shell into a shared, machine-wide cache at ~/.cache/puppeteer. That download needs network access and about 650 MB of disk (measured on Linux with puppeteer@25.8.0: 391 MB for chrome, 261 MB for chrome-headless-shell). The cache is shared across projects, so a machine that already has it pays nothing extra.

To skip it, install with PUPPETEER_SKIP_DOWNLOAD=1. Everything except SVG/PNG rendering then works unchanged; those three calls fail until you point the server at an existing browser:

export PUPPETEER_EXECUTABLE_PATH="/usr/bin/google-chrome"

make install never downloads a browser: the installer runs its private npm install with PUPPETEER_SKIP_DOWNLOAD=true, so the installed server renders only if this checkout's npm ci already filled the shared cache, a system Chrome/Chromium is on PATH, or PUPPETEER_EXECUTABLE_PATH is set. make doctor reports which of those applies as SVG browser readiness.

Chrome refuses to start as root, and container, devcontainer, CI, and cloud sandbox images commonly run the server as uid 0. The server therefore launches Chrome with --no-sandbox --disable-setuid-sandbox when process.getuid() is 0. Set MCP_BPMN_BROWSER_ARGS to a space-separated argument list to replace that default anywhere else the sandbox cannot start — for example on hosts that restrict unprivileged user namespaces — or to an empty string to launch Chrome with no extra arguments at all.

Install for Codex and Claude Code

git clone https://github.com/sebahrens/bpmn-mcp.git
cd mcp-bpmn
npm ci
make install
make doctor

make install builds a private release, registers every supported client found on PATH, and copies the bpmn-modeler skill into each detected client. Start a new client session, then ask it to create a small BPMN process and export XML. Each stdio session uses its canonical launch directory as the managed workspace by default, so the same registration follows Codex or Claude Code across repositories.

See agent client installation and operation for targeted installs, custom paths, updates, verification, the first safe BPMN workflow, and generic MCP-only setup. See installation troubleshooting for WSL, browser, registration-conflict, and recovery guidance.

make uninstall removes installer-owned program files, registrations, and skill copies but preserves diagrams by default.

Generic stdio setup

Clients other than Codex and Claude Code can launch the source checkout directly:

npm run build
npm start

npm run build emits the canonical ESM executable at dist/server/index.js. For a generic MCP client, configure command as the absolute result of command -v node and args as the absolute checkout path to dist/server/index.js. The server uses stdio, so it normally appears idle when started in a terminal.

To use the stable executable created by make install instead, obtain its absolute path from make doctor and configure it as command with an empty args array. Generic MCP clients receive the server's built-in workflow instructions but do not automatically discover the optional Agent Skill.

Install a packed release artifact

This repository currently documents an npm tarball install rather than assuming that bpmn-mcp is available from the public npm registry. A release producer can build the canonical CLI-only artifact from a source checkout:

artifact_dir=$(mktemp -d)
npm pack --pack-destination "$artifact_dir"

Install that tarball into a dedicated consumer directory and run its packaged executable:

consumer_dir=$(mktemp -d)
npm install --prefix "$consumer_dir" "$artifact_dir"/bpmn-mcp-*.tgz
"$consumer_dir/node_modules/.bin/bpmn-mcp"

For an MCP client, use the absolute value of $consumer_dir/node_modules/.bin/bpmn-mcp as command and an empty args array. The package is a CLI, not an importable JavaScript library.

Agent plugins and evaluations

The checkout contains Codex and Claude Code plugin metadata for development and release validation. Public marketplace installation is a later distribution path; no public marketplace entry is claimed here. Do not combine a development plugin with a same-named user MCP registration without first following the conflict checks.

The deterministic cross-client workflow evaluation is safe for development and CI:

npm run test:evaluations

Authenticated model runs are opt-in. Build first, then select one bounded case while iterating:

npm run build
npm run eval:codex -- --case direct-process-svg
npm run eval:claude -- --case direct-process-svg

The Codex adapter runs codex exec in a temporary project containing the canonical skill and a project-scoped stdio MCP configuration. The Claude adapter materializes the same cases as native claude plugin eval cases in a temporary plugin copy. Both set MCP_BPMN_DIAGRAMS_PATH to a temporary directory, copy only declared setup fixtures there, and remove the directory afterward; they never read, overwrite, or delete diagrams from the user's real store. Omit --case to run the complete corpus. These commands can consume model quota and are intentionally excluded from npm run check and CI.

Optional CommonJS bundle

The CommonJS bundle is a separate source-checkout build and is not produced by npm run build or included in the canonical npm tarball:

npm run build:bundle
npm run start:bundle

📚 API Reference

Stateful Context Management

MCP-BPMN uses a stateful API design where you work with one diagram at a time. All operations apply to the current diagram context, eliminating the need for processId parameters.

Advertised tool matrix

The headings in this API reference enumerate every tool returned by tools/list. The executable parity baseline is tests/contracts/engine-contract.test.ts, with focused behavior in the unit, integration, and end-to-end suites.

Each advertised tool also includes the standard MCP readOnlyHint, destructiveHint, idempotentHint, and openWorldHint annotations. These annotations describe observable server behavior: authoring calls auto-save, replacement and deletion calls may destroy existing state, and all operations stay within the configured local diagram store. MCP annotations are advisory hints, not an authorization boundary; clients must still apply their own trust and approval policies.

Area

Advertised tools

Tested scope and boundary

Context creation/import

new_bpmn, new_from_mermaid, open_bpmn, open_mermaid_file

Process or collaboration roots; documented Mermaid subset; imports must fit the server's canonical model

Context lifecycle

save, save_as, close, current

One active diagram and filename; local atomic persistence

Authoring

add_event, add_activity, add_gateway, add_data_object, add_text_annotation, add_pool, add_lane

The explicit schema enums and typed properties below, not arbitrary BPMN elements or extension attributes

Relationships

connect, add_association

connect authors a sequence flow within one process, or a message flow across participants of a collaboration; associations are artifact relationships

Query/mutation

list_elements, get_element, list_connections, get_connection, update_element, update_connection, update_element_geometry, update_connection_geometry, apply_geometry_patch, route_connection, delete_element

Paginated queries, typed semantic updates, guarded BPMNShape/BPMNEdge geometry updates, and proposal-first local rerouting

Bulk authoring

build_process

Many nodes and the flows between them in one atomic call, using caller-chosen ref names; the same per-element validation applies

Export/quality

export, save_svg, save_png, validate, analyze_geometry, auto_layout

XML or browser-backed SVG export; managed SVG/PNG artifact persistence; structural and geometry diagnostics; left-to-right or top-to-bottom layout

Workspace and stored files

get_workspace, select_workspace, list_diagrams, delete_diagram_file, get_diagrams_path

Per-session repository discovery and sandboxed access inside the selected workspace; rendered artifacts remain separate from managed BPMN listings; get_diagrams_path is a compatibility alias

Creation Tools

new_bpmn

Create a new BPMN process or collaboration diagram and set it as the current context.

{
  name: "Order Processing",
  filename: "order-processing.bpmn", // optional; see Diagram filenames
  type: "process" // or "collaboration" (optional, defaults to "process")
}

Omitting filename is safe: the server generates a placeholder name for autosave and save_as removes it when you pick a real one. See Diagram filenames.

new_from_mermaid

Create a new BPMN diagram from Mermaid code and set it as the current context.

{
  name: "My Process",
  filename: "my-process.bpmn", // optional; see Diagram filenames
  mermaidCode: "graph TD\n  A[Start] --> B[Task] --> C[End]"
}

Mermaid conversion intentionally supports a focused flowchart subset:

Mermaid construct

BPMN mapping

[Task]

Task (the exact labels Start/Begin and End/Stop/Finish become events)

((Event))

Start/end event when topology identifies one; otherwise intermediate throw event

{Decision}

Exclusive gateway

[/Subprocess/]

Subprocess

[[Data]]

Standalone data object reference linked to a backing data object

`-->

Label

subgraph id[Name]

Participant with its own process; cross-subgraph edges become message flows

When any subgraph is present, every node must belong to exactly one top-level subgraph. Nested subgraphs and sequence-flow connections to data nodes are rejected before BPMN export. Styling, click handlers, CSS classes, and dotted edge appearance are not represented in BPMN; accepted lossy syntax returns a conversion warning. Text labels and subgraph names are XML-escaped and round-trip through BPMN unchanged.

preview_mermaid

Dry-run the same conversion and report what each node and edge became, without creating a diagram, writing a file, or replacing the current context. Use it to check an ambiguous node before committing to new_from_mermaid.

{
  mermaidCode: "flowchart TD\n  A((Start)) --> B[Review] --> C{Approved?}"
}

The result lists every node as { mermaidId, elementId, type, name, ownerId }, every edge as { connectionId, type, sourceId, targetId, label } with its sequence- or message-flow classification, the pools each subgraph produced, and the conversion warnings. Layout is skipped: the preview answers what each node became, not where it will sit.

Mermaid has no form for parallel or inclusive gateways, user or service tasks, or message and timer events. Import first, then create or adjust those with add_gateway, add_activity, and add_event.

File Operations

open_bpmn

Open an existing BPMN file and set it as the current context.

{
  filename: "my-process.bpmn"
}

open_mermaid_file

Open and convert a Mermaid file to BPMN, setting it as the current context.

{
  filename: "my-flowchart.mmd",
  bpmnFilename: "my-flowchart.bpmn" // optional; names the converted diagram
}

save

Atomically save the current diagram to its active file. New and opened diagrams already have an active filename, and successful mutations autosave to that same file.

{}

save_as

Atomically save the current diagram with a new filename and make that filename active. Later mutations update only the new file.

If the previous filename was a server-generated placeholder, it is deleted so the diagram does not exist twice; the result reports previousFilename and removedPreviousFile. A filename you chose yourself is kept as an unchanged snapshot. See Diagram filenames.

{
  filename: "my-process.bpmn"
}

close

Close the current diagram and clear the context.

{}

current

Get information about the current diagram.

{}

Element Manipulation Tools

add_event

Add events (start, end, intermediate, boundary) to the current diagram.

{
  eventType: "start", // start, end, intermediate-throw, intermediate-catch, boundary
  name: "Order Received",
  eventDefinition: "message", // optional; only BPMN-legal event kind/definition pairs are accepted
  eventDefinitionPayload: {
    reference: { name: "Order received" } // root ID is generated when omitted
  },
  position: { x: 100, y: 200 } // optional
}

Timer definitions require timer: { type: "timeDate" | "timeDuration" | "timeCycle", expression, language? }; conditional definitions require condition: { expression, language? }. Error and escalation references may also include code. Compensation throws may include activityRef and waitForCompletion; compensation boundary events are non-interrupting.

add_activity

Add activities (tasks, subprocesses) to the current diagram.

{
  activityType: "userTask", // task, userTask, serviceTask, scriptTask, etc.
  name: "Review Order",
  position: { x: 250, y: 200 }, // optional
  properties: { // optional; Camunda 7 profile only on userTask
    assignee: "reviewer",
    candidateGroups: ["operations", "approvers"],
    dueDate: "${dueDate}"
  }
}

New BPMN and Mermaid-authored documents accept extensionProfile: "portable" | "camunda7"; the default is portable. Portable mode rejects the three vendor fields and emits no vendor namespace. Camunda updates accept null for any of them to remove the corresponding XML attribute. Candidate group entries cannot contain commas. Imported BPMN detects actual Camunda namespace use and preserves other warning-free extensions opaquely.

Call activities serialize as bpmn:callActivity. Their optional properties.calledElement is a lexical BPMN QName identifying the callable element; it is not required to match a process ID in the current diagram.

Activities may use standard BPMN multi-instance loop characteristics. Set isSequential to false for parallel instances or true for sequential instances:

{
  activityType: "serviceTask",
  name: "Process Batch",
  properties: {
    multiInstance: {
      isSequential: false,
      loopCardinality: {
        body: "requestedInstanceCount",
        language: "urn:example:expression-language"
      },
      completionCondition: {
        body: "completedInstanceCount >= requiredInstanceCount",
        language: "urn:example:expression-language"
      },
      loopDataInputRef: "DataObjectReference_Input",  // optional ItemAwareElement ID
      loopDataOutputRef: "DataObjectReference_Output" // optional ItemAwareElement ID
    }
  }
}

The server preserves expression bodies exactly and serializes them as BPMN FormalExpression values. It does not parse or evaluate them, so choose a language/profile supported by the BPMN engine that will execute the exported diagram. The loop data references must identify existing BPMN ItemAwareElement instances; the portable schema does not emit a vendor-specific collection attribute. Vendor-specific binding or version attributes are not emitted by the portable BPMN dialect.

{
  activityType: "callActivity",
  name: "Invoke fulfillment",
  properties: { calledElement: "FulfillmentProcess" }
}

add_gateway

Add gateways for branching logic to the current diagram.

{
  gatewayType: "exclusive", // exclusive, parallel, inclusive, eventBased, complex
  name: "Payment Check",
  position: { x: 400, y: 200 } // optional
}

add_data_object

Add a visible bpmn:dataObjectReference and its linked, non-rendered bpmn:dataObject. Collection state belongs to the backing object. An optional itemSubjectRef must identify an existing bpmn:itemDefinition, such as one loaded from an imported diagram.

{
  name: "Order records",
  position: { x: 400, y: 320 }, // optional reference position
  isCollection: true, // optional, defaults to false
  itemSubjectRef: "ItemDefinition_Order" // optional existing definition ID
}

Data input/output associations are activity-owned BPMN constructs and are not created by add_association, which remains the generic artifact association.

add_text_annotation

Add a BPMN text annotation. Text is preserved exactly, including line breaks and XML metacharacters. textFormat defaults to BPMN's text/plain; position and size default to the engine's annotation geometry. Supplying associatedElementId also creates a separate, undirected BPMN association from the annotation to that element.

{
  text: "Review the exception path\nbefore approval",
  textFormat: "text/markdown", // optional
  position: { x: 400, y: 320 }, // optional
  size: { width: 220, height: 80 }, // optional
  associatedElementId: "UserTask_1" // optional
}

connect

Connect two elements in the current diagram. Endpoints in the same process and scope get a sequence flow; endpoints belonging to different participants of a collaboration, black-box pools included, get a message flow. The connection type follows from the endpoints, so there is no type argument.

{
  sourceId: "ExclusiveGateway_1",
  targetId: "UserTask_1",
  label: "Start Flow", // optional
  condition: "amount > 1000", // optional, for conditional sequence flows
  conditionLanguage: "FEEL", // optional
  conditionType: "bpmn:FormalExpression", // optional
  isDefault: false // optional; default flows cannot have conditions
}

Conditions and defaults are supported for activities and exclusive, inclusive, or complex gateways. A default flow cannot also have a condition, and neither applies to a message flow. The result reports the connectionType that was created, so a caller can confirm which kind it got.

add_association

Add a BPMN association artifact between two BaseElements in a compatible process or collaboration scope. This is distinct from sequence and message flows. associationDirection defaults to BPMN's None value.

{
  sourceId: "TextAnnotation_1",
  targetId: "UserTask_1",
  associationDirection: "One" // None, One, or Both
}

add_pool

Add a pool (participant) to a collaboration diagram.

{
  name: "Customer",
  position: { x: 100, y: 100 }, // optional
  size: { width: 600, height: 250 }, // optional
  blackBox: false // optional; true creates a participant without an owned process
}

add_lane

Add a lane to a white-box pool and assign direct process flow nodes to it. Nodes already assigned to another lane are moved to the new lane.

{
  poolId: "Participant_1",
  name: "Sales Department",
  flowNodeIds: ["StartEvent_1", "UserTask_1"],
  position: "bottom" // optional
}

Query and Manipulation Tools

list_elements

List a stable, ID-ordered page of elements and association artifacts in the current diagram. Filter with elementType: "bpmn:Association" to list only associations.

{
  elementType: "bpmn:Task", // optional filter
  limit: 100, // optional, defaults to 100; maximum 500
  offset: 0 // optional, defaults to 0
}

The response is { count, returnedCount, offset, limit, hasMore, elements, revision }. Compatibility note: the pagination envelope replaces the earlier bare-array response; clients written against that contract must now read elements. The existing element fields retain their meanings. Rendered elements also expose shapeId, bounds, and optional labelBounds; additional metadata fields and lane entries may be present.

get_element

Get details of a specific element or association.

{
  elementId: "UserTask_1"
}

list_connections

List a stable, ID-ordered page of SequenceFlow, MessageFlow, and Association connections. Optional filters select a connection type, endpoint, owner, or scope. Each result includes semantic fields, BPMN DI waypoints, and the current semantic, geometry, and document revisions.

{
  connectionType: "bpmn:MessageFlow", // optional
  sourceId: "SendTask_1", // optional
  limit: 100,
  offset: 0
}

get_connection

Get the complete semantic and rendered geometry state for one SequenceFlow, MessageFlow, or Association. Use the returned revisions as compare-and-set guards for connection mutations and routing.

{
  connectionId: "Flow_1"
}

update_element

Update element properties.

{
  elementId: "UserTask_1",
  name: "Updated Task Name",
  properties: { assignee: "john.doe", candidateGroups: ["reviewers"] },
  defaultFlow: "Flow_2" // outgoing flow ID, or null to clear
}

update_connection

Update SequenceFlow, MessageFlow, or Association semantics without replacing the connection ID. Labels may be cleared with null; SequenceFlow conditions may be replaced or cleared, default ownership may be toggled, and Association direction may be changed. Supply either the semanticRevision returned by get_connection or the current document revision. Changing either endpoint requires explicit snap-to-boundary, which validates and attaches the retained route to the new endpoint shapes before the atomic autosave.

{
  connectionId: "Flow_1",
  targetId: "Task_3", // optional
  label: "Approved", // optional; null clears
  condition: { body: "${approved}", language: "FEEL" }, // null clears
  isDefault: false, // SequenceFlow only
  endpointPolicy: "snap-to-boundary", // required when an endpoint changes
  expectedSemanticRevision: "sha256:...",
  collisionPolicy: "reject-new" // or "warn" / "allow"
}

update_element_geometry

Move or resize one rendered element with atomic autosave. Connected shapes require incidentConnectionPolicy; use snap-endpoints to keep incident edges attached or reject to refuse the change. Newly introduced collisions are rejected unless collisionPolicy: "allow" is explicit. Use dryRun to receive the proposed before/after geometry and diagnostics without changing the file.

{
  elementId: "UserTask_1",
  bounds: { x: 420, y: 180, width: 120, height: 90 },
  labelBounds: { x: 430, y: 275, width: 100, height: 20 }, // optional; null clears
  expectedBounds: { x: 300, y: 180, width: 100, height: 80 }, // optional CAS guard
  expectedRevision: "sha256:...:v4", // optional optimistic-concurrency guard
  collisionPolicy: "reject", // or "allow"; defaults to "reject"
  incidentConnectionPolicy: "snap-endpoints", // required for connected moves/resizes
  dryRun: false
}

update_connection_geometry

Replace all waypoints for one rendered connection with atomic autosave. Exact endpoints must already attach to the source and target boundaries; snap-to-boundary adjusts both endpoints while preserving interior waypoints. Omitting labelBounds preserves the edge label and null clears it. Use either expectedWaypoints or the geometryRevision returned by get_connection as a compare-and-set guard. Newly introduced error diagnostics are rejected by default; warn and allow apply while returning the resulting diagnostics.

{
  connectionId: "Flow_1",
  waypoints: [{ x: 200, y: 140 }, { x: 300, y: 140 }, { x: 400, y: 140 }],
  labelBounds: null, // optional; omission preserves the current BPMNLabel
  expectedGeometryRevision: "sha256:...", // optional geometry CAS guard
  expectedRevision: "sha256:...:v5", // optional document CAS guard
  endpointPolicy: "exact", // or "snap-to-boundary"; defaults to "exact"
  collisionPolicy: "reject-new", // or "warn" / "allow"
  dryRun: false
}

apply_geometry_patch

Update up to 256 rendered elements and connections in one atomic commit. The server applies every shape, label, and route update to a private candidate, then evaluates diagnostics against that complete final geometry. Supply either expectedRevision for the whole patch or per-object before guards. Any stale guard, invalid final geometry, rejected diagnostic, or save failure leaves both memory and disk unchanged.

{
  expectedRevision: "sha256:...:v6",
  elementUpdates: [{
    elementId: "UserTask_1",
    bounds: { x: 500, y: 180, width: 120, height: 90 },
    labelBounds: { x: 510, y: 275, width: 100, height: 20 }
  }],
  connectionUpdates: [{
    connectionId: "Flow_1",
    waypoints: [{ x: 200, y: 140 }, { x: 500, y: 225 }],
    endpointPolicy: "exact"
  }],
  collisionPolicy: "reject-new", // or "warn" / "allow"
  dryRun: false
}

route_connection

Generate ranked orthogonal routing candidates for one SequenceFlow, MessageFlow, or Association. The default is proposal-only: memory, disk, and the document revision remain unchanged. The returned geometryPatch can be passed directly to apply_geometry_patch. Set apply: true to commit the best collision-free candidate in one atomic autosave. The router scores shape and label collisions, clearance failures, crossings with existing connections, bends, and length while preserving every unrelated DI object.

{
  connectionId: "Flow_1",
  avoidElementIds: ["Task_Obstacle"],
  avoidConnectionIds: ["Flow_Existing"],
  clearance: 20,
  preserveOtherGeometry: true,
  expectedGeometryRevision: "sha256:...", // optional geometry CAS guard
  apply: false // proposal-only by default
}

If no acceptable route exists, the tool returns a routing_failed error with ranked candidate geometry, score breakdowns, and diagnostics without mutation.

build_process

Create many elements and the flows between them in one atomic call. Each node carries a caller-chosen ref that flows in the same request use to name it; the server assigns the real BPMN IDs and returns the mapping. A flow endpoint that is not a ref is treated as the ID of an element already in the diagram. The same validation applies as for the individual add_* and connect tools, and nothing is written unless every step succeeds. Run auto_layout afterwards to place the result.

{
  nodes: [
    { kind: "event", ref: "start", eventType: "start", name: "Request received" },
    { kind: "activity", ref: "review", activityType: "userTask", name: "Review" },
    { kind: "gateway", ref: "decide", gatewayType: "exclusive", name: "Approved?" },
    { kind: "activity", ref: "pay", activityType: "serviceTask", name: "Pay" },
    { kind: "event", ref: "done", eventType: "end", name: "Done" }
  ],
  flows: [
    { source: "start", target: "review" },
    { source: "review", target: "decide" },
    { source: "decide", target: "pay", label: "yes", condition: "${approved}" },
    { source: "decide", target: "done", label: "no", isDefault: true },
    { source: "pay", target: "done" }
  ]
}

Returns elements (each with its ref, assigned elementId and BPMN type), connections, and the usual revision fields.

delete_element

Delete an element and its incident connections. Passing an association ID deletes only that association and leaves its endpoints intact; deleting an endpoint, including a text annotation, cascades to its associations.

{
  elementId: "Task_1"
}

Utility Tools

export

Export the current diagram as BPMN 2.0 XML or a rendered SVG.

{
  format: "xml", // "xml" or "svg"; defaults to "xml"
  formatted: true // optional; applies to XML and defaults to true
}

XML export returns text and does not launch a browser. SVG export launches a headless browser through Puppeteer, renders with bpmn-js, sanitizes the result, and returns an embedded image/svg+xml resource. It requires an available Chrome/Chromium executable and retains the visible bpmn.io attribution described under License.

save_svg

Render the current diagram and atomically persist a separate SVG artifact in the managed workspace. The required filename must use the .svg extension. Existing files are preserved unless overwrite is explicitly true.

{
  filename: "order-review.svg",
  overwrite: false // optional; defaults to false
}

SVG artifacts use the same sanitization and visible bpmn.io attribution as export.

save_png

Render the current diagram and atomically persist a separate PNG artifact in the managed workspace. The required filename must use the .png extension. Existing files are preserved unless overwrite is explicitly true.

{
  filename: "order-review.png",
  overwrite: false, // optional; defaults to false
  scale: 1 // optional pixel density, 1 to 4; defaults to 1
}

PNG is rasterized from the same sanitized SVG that save_svg writes. scale becomes the browser's device pixel ratio, so text and strokes are resampled rather than stretched. The result reports width, height, scale, and downscaled; a diagram whose raster would exceed 4,096 px on a side or 16 million pixels is reduced below the requested scale and says so instead of shrinking silently.

Both tools render from the active BPMN snapshot without changing its XML, revision, or active .bpmn filename. Rendered output is capped at 5 MiB by default and can be configured with MCP_BPMN_MAX_ARTIFACT_BYTES. Filenames are basename-only and traversal-safe. list_diagrams and delete_diagram_file continue to operate only on BPMN XML files, keeping diagram and rendered-artifact operations explicit.

validate

Validate the current diagram structure.

{
  level: "full" // "syntax", "semantic", or "full"; defaults to "full"
}

Validation levels are cumulative. syntax parses XML and resolves references; semantic adds owner-aware event, flow, subprocess, lane, and collaboration rules; full also adds executable-profile start/end/connectivity guidance.

analyze_geometry

Inspect the whole diagram or selected element and connection IDs for missing DI, endpoint gaps, overlaps, crossings, containment failures, minimum clearance, and optional non-orthogonal routes. The response includes stable severity-coded diagnostics, a summary, and the relevant shapes, edges, and labels.

{
  elementIds: ["DataObjectReference_1"], // optional
  connectionIds: ["MessageFlow_1"], // optional
  clearance: 5,
  tolerance: 1,
  requireOrthogonal: true
}

auto_layout

Apply automatic layout to position elements in the current diagram.

{
  algorithm: "horizontal", // currently only horizontal is supported
  direction: "left-to-right" // or "top-to-bottom"
}

direction chooses the reading direction. top-to-bottom reflects the ranked layout across the diagonal: flows run downward, pools become vertical bands, and edge endpoints are re-docked onto the borders they now face. There are no spacing, subset, or pinned-element controls yet, so every coordinate the layout touches is replaced.

A layout that reproduces the geometry the diagram already has is not committed. The call returns changed: false, leaves the revision alone, and does not rewrite the file, so running auto_layout twice is free the second time.

Layout runs in a killable subprocess with a default five-second budget. A benchmark-derived preflight accepts at most 2,000 elements, 2,000 connections, and 10 connections per element; inputs over any limit reject before layout. For collaborations, each participant process is ranked independently, so message flows do not change its sequence-flow order. Auto-layout replaces manual node and container coordinates, but requested/imported participant and lane dimensions remain lower bounds. Pools are then stacked without overlap; lanes and owned nodes remain contained, and message flows are routed only after the final pool placement. Disconnected nodes are packed deterministically in their owner process, nested subprocesses retain semantic containment, and black-box participants keep their requested minimum size without fabricated process content.

File Management Tools

list_diagrams

List a stable, filename-ordered page of saved BPMN diagrams.

{
  limit: 100, // optional, defaults to 100; maximum 500
  offset: 0 // optional, defaults to 0
}

The existing { count, diagrams, path } response fields remain available; returnedCount, offset, limit, and hasMore describe the selected page. Only files on the selected page are read for embedded BPMN metadata, and the aggregate metadata read is capped at 5 MiB by default.

delete_diagram_file

Delete a saved diagram file.

{
  filename: "old-process.bpmn"
}

get_diagrams_path

Get the current workspace path. This compatibility alias predates the richer workspace discovery response.

{}

get_workspace

Report the canonical launch cwd, immutable startup boundary, current workspace, and whether it came from the environment, repository config, launch cwd, or a session selection.

{}

select_workspace

Select another workspace below the startup boundary for this stdio session. Changing workspaces closes the active diagram; successful prior mutations are already autosaved.

{
  path: "wiki/processes/assets"
}

🔄 Context Management

The MCP-BPMN server uses a stateful design where you work with one diagram at a time:

  1. Create or Open: Start by creating a new diagram (new_bpmn, new_from_mermaid) or opening an existing one (open_bpmn, open_mermaid_file)

  2. Manipulate: All operations (add_event, connect, etc.) apply to the current diagram

  3. Save: Save your work with save or save_as

  4. Close: Close the current diagram with close

If you try to perform operations without a current context, you'll get a helpful error message:

No current context. Please create a diagram first with:
  - new_bpmn(name) to create a new BPMN diagram
  - new_from_mermaid(name, mermaidCode) to convert from Mermaid
  - open_bpmn(filename) to open an existing BPMN file
  - open_mermaid_file(filename) to convert a Mermaid file

💡 Examples

Example 1: Creating an Approval Process from Scratch

// Step 1: Create a new process (sets it as current context)
await new_bpmn({ name: "Approval Workflow" });

// Step 2: Add elements. Every add_* result carries the generated `elementId`;
// keep it instead of guessing. IDs come from per-type session counters, and a
// rejected call still consumes a number, so "StartEvent_1" only holds on a
// server that has never failed a call.
const start = await add_event({ eventType: "start", name: "Request Received" });
const review = await add_activity({ activityType: "userTask", name: "Review Request" });
const decision = await add_gateway({ gatewayType: "exclusive", name: "Approved?" });
const approve = await add_activity({ activityType: "serviceTask", name: "Process Approval" });
const reject = await add_activity({ activityType: "userTask", name: "Handle Rejection" });
const complete = await add_event({ eventType: "end", name: "Complete" });

// Step 3: Connect elements using the returned IDs
await connect({ sourceId: start.elementId, targetId: review.elementId });
await connect({ sourceId: review.elementId, targetId: decision.elementId });
await connect({ sourceId: decision.elementId, targetId: approve.elementId, label: "Yes" });
await connect({ sourceId: decision.elementId, targetId: reject.elementId, label: "No" });
await connect({ sourceId: approve.elementId, targetId: complete.elementId });
await connect({ sourceId: reject.elementId, targetId: complete.elementId });

// Step 4: Apply auto-layout for proper positioning
await auto_layout();

// Step 5: Save and export the diagram
await save_as({ filename: "approval-workflow.bpmn" });
const xml = await export();
// Step 1: Create from Mermaid syntax (much more concise!)
await new_from_mermaid({ 
  name: "Approval Workflow",
  extensionProfile: "camunda7",
  mermaidCode: `
    graph TD
      A((Request Received)) --> B[Review Request]
      B --> C{Approved?}
      C -->|Yes| D[Process Approval]
      C -->|No| E[Handle Rejection]
      D --> F((Complete))
      E --> F
  `
});

// Step 2: Apply auto-layout (Mermaid conversion includes basic layout)
await auto_layout();

// Step 3: Look up the imported IDs before editing. Mermaid node keys become the
// ID suffix, and every Mermaid box becomes a plain `bpmn:Task`, so this import
// yields StartEvent_A, Task_B, Gateway_C, Task_D, Task_E, and EndEvent_F.
const { elements } = await list_elements({});
const review = elements.find(element => element.name === "Review Request");

// `assignee` is rejected on `bpmn:Task` ("assignee is only valid on
// bpmn:UserTask"), so rename here and add a real user task with add_activity
// when you need user-task properties.
await update_element({
  elementId: review.id,
  name: "Review Request (SLA 2 days)"
});

// Step 4: Save and export
await save_as({ filename: "approval-workflow.bpmn" });
const xml = await export();

Example 3: Working with Multiple Diagrams

// Create first diagram
await new_bpmn({ name: "Process A" });
await add_event({ eventType: "start" });
await add_activity({ activityType: "task", name: "Task A" });
await save_as({ filename: "process-a.bpmn" });

// Create second diagram (automatically closes the first)
await new_bpmn({ name: "Process B" });
await add_event({ eventType: "start" });
await add_activity({ activityType: "task", name: "Task B" });
await save_as({ filename: "process-b.bpmn" });

// Go back to first diagram
await open_bpmn({ filename: "process-a.bpmn" });
await add_event({ eventType: "end" });
await save();

// Check current diagram info
const info = await current();
console.log(info); // Shows: { name: "Process A", filename: "process-a.bpmn", ... }

🗂️ File Storage

BPMN diagrams are automatically saved in the canonical directory from which the MCP client launched the stdio child. A repository may narrow storage to a relative descendant with .mcp-bpmn.json:

{
  "path": "wiki/processes/assets"
}

Dot segments, absolute repository-config paths, and symlink traversal are rejected. Use get_workspace to inspect the launch cwd, immutable startup boundary, current workspace, and resolution source. select_workspace may narrow the current session to another relative descendant and closes the active diagram when the workspace changes; it never changes the Node process cwd.

An explicit absolute environment override remains available for clients that do not propagate the intended repository cwd:

export MCP_BPMN_DIAGRAMS_PATH=/custom/path

src/config/index.ts defines every other supported variable. This is the complete set the server reads at runtime (MCP_BPMN_LAYOUT_CANDIDATES, listed under Development, is a test-suite flag and has no effect on the server):

Variable

Effect

Default

MCP_BPMN_DIAGRAMS_PATH

Absolute workspace override; must have no dot segments

launch cwd

MCP_BPMN_MAX_IMPORT_BYTES

Largest accepted BPMN import

5 MiB

MCP_BPMN_MAX_IMPORT_ELEMENTS

Elements accepted per import

10,000

MCP_BPMN_MAX_IMPORT_FLOWS

Flows accepted per import

20,000

MCP_BPMN_MAX_IMPORT_DI_ELEMENTS

DI elements accepted per import

30,000

MCP_BPMN_MAX_MERMAID_BYTES

Largest accepted Mermaid input

5 MiB

MCP_BPMN_MAX_ARTIFACT_BYTES

Largest rendered SVG/PNG written by save_svg/save_png

5 MiB

MCP_BPMN_MAX_LAYOUT_ELEMENTS

Elements accepted per layout

2,000

MCP_BPMN_MAX_LAYOUT_CONNECTIONS

Connections accepted per layout

2,000

MCP_BPMN_MAX_LAYOUT_DENSITY

Connections per element accepted per layout

10

MCP_BPMN_MAX_LAYOUT_BYTES

Largest XML handed to the layout subprocess

5 MiB

MCP_BPMN_MAX_CONCURRENT_LAYOUTS

Simultaneous layout subprocesses

2

MCP_BPMN_MAX_LISTING_ITEMS

Directory entries scanned by list_diagrams

10,000

MCP_BPMN_MAX_LISTING_METADATA_BYTES

Total diagram bytes read for listing metadata

5 MiB

MCP_BPMN_LAYOUT_TIMEOUT_MS

Layout subprocess deadline

5,000 ms

MCP_BPMN_SHUTDOWN_TIMEOUT_MS

Graceful shutdown deadline

15,000 ms

MCP_BPMN_BROWSER_ARGS

Space-separated list that replaces the Chrome command line used for SVG/PNG rendering

--no-sandbox --disable-setuid-sandbox under uid 0, otherwise none

A numeric variable that is not a positive number — a typo, 0, or a negative value — is ignored and the default applies, so a malformed override can never disable a limit. Read the defaults from src/config/index.ts rather than pinning them in deployment documentation. The layout defaults come from local sparse/dense benchmarks recorded in that file: 2,000/1,999 completed in about 1.4s, 25/300 took about 4.8s, and 26/325 exceeded five seconds.

On SIGINT, SIGTERM, or stdin EOF, the server stops accepting tool calls and allows accepted operations and their atomic persistence to finish before it closes renderer/layout subprocesses and the stdio transport. Graceful shutdown has a hard 15-second deadline; exceeding it forces a nonzero exit.

Diagram filenames

Each diagram has exactly one active filename, and every successful mutation serializes and atomically autosaves to it. A failed serialization or write leaves both memory and disk at the last successful state.

new_bpmn, new_from_mermaid, and open_mermaid_file all accept an optional filename (filename, or bpmnFilename on open_mermaid_file). Pass one and that name is the active filename from the first autosave; a name with no extension gets .bpmn appended.

Omit it and the server generates a placeholder name instead, so that autosave has somewhere to write before you have chosen a name. The placeholder is not meant to be read by a human:

mcp-bpmn-v1_<base64url of ["<processId>","<name>","<uuid>"]>.bpmn

Encoding the metadata is what lets list_diagrams report the exact process ID and name without opening the file. If that encoded name would exceed 200 bytes, the server falls back to {processId}_{sanitizedName}_{uuid}.bpmn; the 200-byte ceiling leaves room for the atomic-write suffix inside one 255-byte filesystem component.

save_as adopts the name you give it and deletes the placeholder it replaces, so a diagram that started unnamed does not leave an orphan duplicate behind. Its result reports previousFilename and removedPreviousFile. A filename you chose yourself is never deleted on your behalf: calling save_as on a named diagram leaves the previous file in place as an unchanged snapshot. Opening a file adopts that file's name, which is likewise never a placeholder.

🏗️ Architecture

Technology Stack

  • TypeScript - Type-safe development

  • Node.js - Runtime environment

  • MCP SDK - Model Context Protocol implementation

  • Jest - Testing framework

Key Components

  • SimpleBpmnEngine (src/core/) - Canonical BPMN document mutation, persistence, and XML export

  • BpmnDocument (src/core/) - Typed, moddle-backed model and XML serialization

  • BpmnValidator (src/core/) - Syntax, semantic, and full validation levels

  • BpmnSvgRenderer (src/core/) - Isolated, browser-backed bpmn-js SVG rendering

  • DiagramContext (src/core/) - Stateful context management for current diagram

  • BpmnAutoLayoutV2Adapter (src/core/layout/) - The one layout path; runs bpmn-auto-layout in a bounded subprocess

  • BpmnRequestHandler (src/server/) - MCP request validation and dispatch

  • MermaidConverter / MermaidParser (src/converters/) - Mermaid to BPMN conversion

  • WorkspaceSession (src/config/) - Launch cwd, startup boundary, and workspace selection

  • FileManager / SafeFileStore (src/utils/) - Bounded, atomic, root-pinned file operations

Project Structure

mcp-bpmn/
├── src/
│   ├── core/           # BPMN engine, document model, validator, renderer
│   │   └── layout/     # Layout model, adapters, connection routing
│   ├── converters/     # Mermaid parsing and conversion
│   ├── server/         # MCP server, tool schemas, request handlers
│   ├── utils/          # IDs, type mappings, safe file access
│   ├── types/          # TypeScript type definitions
│   └── config/         # Configuration and workspace resolution
├── tests/
│   ├── unit/          # Component tests grouped by source area
│   ├── integration/   # Cross-component behavior
│   ├── contracts/     # Engine and tool-annotation contracts
│   ├── security/      # Adversarial boundary and resource tests
│   ├── e2e/           # Built MCP server protocol tests
│   ├── fixtures/      # BPMN, Mermaid, dialect, and layout inputs
│   ├── helpers/       # Shared test helpers
│   └── mocks/         # Jest/runtime mocks
├── dist/              # Compiled output
└── docs/              # Documentation

🧪 Development

Available Scripts

npm run build        # Build TypeScript
npm run build:bundle # Build CommonJS bundle
npm run build:watch  # Build with watch mode
npm run check        # Complete clean contributor/CI quality gate
npm test             # Source-level tests, then the renderer suite
npm run test:all     # Clean, build, and run every suite including e2e and the loop tests
npm run test:unit    # Unit tests only
npm run test:integration # Integration tests, then the renderer suite
npm run test:e2e     # Clean, build, and run the compiled MCP server tests
npm run test:package # Pack, install, and initialize the published entry points
npm run lint         # Run ESLint
npm run dev          # Development mode with hot reload
npm start            # Start the MCP server

Two suites are excluded from the everyday loop and run only when asked for, or as part of npm run test:all:

npm run test:layout-candidates # Compare the shipped layout against the dev-only alternatives
npm run test:ralph             # Integration tests for ralph-loop/loop.sh

npm test still exercises the shipped layout path across the whole fixture corpus; only the third-party comparison candidates, which cost roughly 54 extra Node subprocesses, are gated behind test:layout-candidates.

Testing

Source-level commands do not read dist/, so an old build cannot affect their result. The suites are:

  • Unit (tests/unit/) - component tests grouped by source area

  • Integration (tests/integration/) - cross-component behavior

  • Contracts (tests/contracts/) - the engine and tool-annotation contracts

  • Security (tests/security/) - adversarial boundary and resource tests

  • E2E (tests/e2e/) - the built MCP server over the protocol

  • Renderer (npm run test:renderer) - real Puppeteer/Chrome rendering

Run tests with:

npm test                    # Source-level tests
npm run test:all            # Clean build plus all tests
npm run check               # Complete clean contributor/CI quality gate
npm run test:coverage       # Source-level tests with coverage
npm run test:watch          # Source-level tests in watch mode

📈 Performance

The canonical release artifact was last measured on 2026-09-04 with Node 22.22.2 and npm 10.9.7 using:

npm pack --dry-run --json

That command reported approximately 410 kB compressed, 2,353,180 unpacked bytes, and 153 files. Most of the unpacked size is not executable code: .js accounts for about 811 kB, TypeScript declarations for about 354 kB, and source maps (.js.map plus .d.ts.map) for about 798 kB together, all emitted because tsconfig.json compiles the whole of src/**/*.

Measure it after a build: npm pack reports only the files that exist, so running it against a cleaned dist/ reports a fraction of the real artifact.

These figures describe the npm tarball, not an installed server: the tarball bundles no production dependencies, while installation resolves the nine direct runtime dependencies in package.json and their transitive dependencies. Puppeteer's managed browser download (see Browser download) is also outside the tarball measurement, and it is far larger than the tarball itself. Re-run the command for the current artifact instead of treating this dated snapshot as a permanent size guarantee.

The optional CommonJS bundle is not the release artifact and has no size claim. Layout input limits and the dated benchmark observations used to choose their defaults are documented under File Storage.

🐛 Known Limitations

  • The authoring API is a focused BPMN 2.0 subset, not complete BPMN 2.0 coverage. Unsupported imported constructs can be rejected rather than edited losslessly.

  • connect infers the connection type from its endpoints rather than taking one. There is no way to ask for a message flow between two nodes that a collaboration would otherwise join with a sequence flow.

  • add_lane authors top-level lanes in white-box pools; it cannot extend an imported nested lane hierarchy.

  • Auto-layout ranks left to right, optionally reflected top to bottom. There are no spacing, subset, or pinned-element controls, and radial algorithms are not advertised.

  • Validation provides the documented syntax, semantic, and full guidance levels; it is not BPMN XSD certification or validation against a deployment engine.

  • The Camunda 7 authoring profile is limited to assignee, candidateGroups, and dueDate on user tasks. It is not general Camunda modeler coverage.

  • SVG export and managed SVG/PNG artifact rendering require Chrome/Chromium through Puppeteer and permit only one concurrent render per server instance. XML workflows remain browser-free.

  • The server does not execute, simulate, or deploy BPMN processes.

🚧 Roadmap

Planned work and known gaps are tracked as Beads issues rather than promised as implemented features in this release document.

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Run the complete quality gate (npm run check)

  4. Commit your changes (git commit -m 'Add amazing feature')

  5. Push to the branch (git push origin feature/amazing-feature)

  6. Open a Pull Request

Code Style

  • TypeScript with strict mode

  • ESLint configuration provided

  • Jest for testing

  • Conventional commits

📝 License

MIT License - see LICENSE file for details.

SVG export and saved SVG/PNG artifacts use bpmn-js@17.11.1. Every exported or saved artifact includes the visible "Powered by bpmn.io" logo linked to https://bpmn.io; clients should not crop, cover, or remove that attribution. See THIRD_PARTY_NOTICES.md for the dependency's license terms and ADR 0002 for the release decision.

📞 Support

  • Issues: GitHub Issues

  • Documentation: See /docs folder for detailed guides

🙏 Acknowledgments

Available Tools

27 tools
add_activityC

Add an activity to the current diagram

Inputs: name (required), activityType (required), ownerId, scopeId, +2 more. Returns: filename, elementId, elementType

add_associationC

Add a BPMN association artifact between two compatible BaseElements

Inputs: sourceId (required), targetId (required), associationDirection. Returns: filename, sourceId, targetId, associationId, +1 more

add_data_objectB

Add a BPMN data object reference and its non-rendered backing data object

Inputs: name (required), ownerId, scopeId, position, +2 more. Returns: filename, referenceId, dataObjectId

add_eventC

Add an event to the current diagram

Inputs: eventType (required), name, ownerId, scopeId, +5 more. Returns: filename, elementId, elementType

add_gatewayC

Add a gateway to the current diagram

Inputs: gatewayType (required), name, ownerId, scopeId, +1 more. Returns: filename, elementId, elementType

add_laneA
Destructive

Add a lane to a white-box pool and assign flow nodes to it. Existing assignments are moved from their previous lane.

Inputs: name (required), poolId (required), flowNodeIds (required), position. Returns: laneId, poolId, filename, assignedFlowNodeCount

add_poolB

Add a pool to the current collaboration diagram

Inputs: name (required), size, blackBox, position. Returns: blackBox, filename, elementId, processId

add_text_annotationA

Add a BPMN text annotation, optionally associated with an existing element

Inputs: text (required), size, position, textFormat, +1 more. Returns: filename, annotationId, associationId

auto_layoutA
DestructiveIdempotent

Apply deterministic automatic layout. Collaboration processes are ranked independently; requested pool/lane sizes are lower bounds, manual coordinates are replaced, disconnected nodes stay in their owner, and message flows route after non-overlapping pool placement.

Inputs: algorithm. Returns: filename, warnings, algorithm, elementCount, +1 more

closeB
Idempotent

Close the current diagram and clear the context

Inputs: no named parameters. Returns: name, filename, processId

connectC

Connect two elements in the current diagram

Inputs: sourceId (required), targetId (required), label, condition, +3 more. Returns: filename, sourceId, targetId, connectionId, +1 more

currentB
Read-onlyIdempotent

Get information about the current diagram

Inputs: no named parameters. Returns: current, diagram

delete_diagram_fileB
DestructiveIdempotent

Delete a saved BPMN diagram file

Inputs: filename (required). Returns: filename, closedCurrent

delete_elementA
DestructiveIdempotent

Delete an element (cascading incident connections) or a connection while preserving its endpoints

Inputs: elementId (required). Returns: filename, elementId, deletedKind, removedConnectionCount

exportA
Read-onlyIdempotent

Export the current diagram as BPMN XML text or an embedded image/svg+xml resource rendered by bpmn-js

Inputs: format, formatted. Returns: uri, format, filename, mimeType, +2 more

get_diagrams_pathA
Read-onlyIdempotent

Get the path where BPMN diagrams are saved

Inputs: no named parameters. Returns: path

get_elementB
Read-onlyIdempotent

Get details of a specific element or association in the current diagram

Inputs: elementId (required). Returns: id, kind, name, size, +13 more

list_diagramsA
Read-onlyIdempotent

List diagrams in stable filename order as { count, returnedCount, offset, limit, hasMore, diagrams, path }; request the next page with offset + returnedCount

Inputs: limit, offset. Returns: path, count, limit, offset, +3 more

list_elementsA
Read-onlyIdempotent

List elements and association artifacts in stable ID order as { count, returnedCount, offset, limit, hasMore, elements }; request the next page with offset + returnedCount

Inputs: limit, offset, elementType. Returns: count, limit, offset, hasMore, +2 more

new_bpmnA

Create a new BPMN diagram and set it as current context

Inputs: name (required), type, extensionProfile. Returns: name, type, filename, processId, +1 more

new_from_mermaidA

Create a new BPMN diagram from Mermaid code and set it as current context

Inputs: name (required), mermaidCode (required), extensionProfile. Returns: name, type, filename, warnings, +4 more

open_bpmnA
Idempotent

Open an existing BPMN file and set it as current context

Inputs: filename (required). Returns: name, type, filename, processId, +3 more

open_mermaid_fileA

Open a Mermaid file, convert it to BPMN, and set as current context

Inputs: filename (required), extensionProfile. Returns: name, type, filename, warnings, +5 more

saveA
DestructiveIdempotent

Save the current diagram to its file (error if no filename set)

Inputs: no named parameters. Returns: name, filename, processId

save_asA
Idempotent

Save the current diagram with a new filename

Inputs: filename (required). Returns: name, filename, processId

update_elementA
DestructiveIdempotent

Update properties of an element in the current diagram

Inputs: elementId (required), name, properties, defaultFlow. Returns: filename, elementId

validateA
Read-onlyIdempotent

Validate the current diagram using cumulative BPMN checks: syntax parses XML and resolves references; semantic adds owner-aware event, flow, subprocess, lane, and collaboration rules; full also adds executable-profile start/end/connectivity guidance

Inputs: level. Returns: level, valid, errors, issues, +3 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 27 tools

    Disambiguation5/5

    Each tool targets a clearly distinct action or resource. Element creation tools are separated by type (event, activity, gateway, data object, annotation, pool, lane), and file operations are distinct (new, open, save, save_as, close, list, delete). No two tools appear to overlap in purpose.

    Naming Consistency4/5

    The naming pattern is mostly consistent with verb-first, underscore-separated names (e.g., add_event, list_elements, delete_diagram_file). Minor deviations exist, such as 'new_from_mermaid' and 'open_mermaid_file' vs. 'open_bpmn', and the noun 'current' as a standalone tool, but overall the convention is coherent.

    Tool Count4/5

    27 tools is above the typical 3-15 range, but the complexity of a BPMN editor justifies the breadth. The tools cover file management, element operations, validation, layout, and export without excess overlap, so the count feels justified rather than bloated.

    Completeness5/5

    The tool surface is remarkably complete for a BPMN diagramming server. It covers full CRUD for elements and files, connections, associations, validation at multiple levels, layout, and export. There are no glaring gaps that would hinder common workflows, including lifecycle operations for diagrams and elements.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to create, manipulate, and manage BPMN 2.0 diagrams programmatically, with support for Mermaid conversion, auto-layout, and file persistence.
      24
      15
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables AI-driven graphical diagram creation and manipulation using natural language, with support for BPMN workflows, analysis, and manual editing via the Model Context Protocol.
      1
      MIT
    • F
      license
      C
      quality
      B
      maintenance
      Enables generating BPMN 2.0 process models from natural language descriptions, YAML, or images via OCR, with templates, validation, and compatibility with tools like Bizagi Modeler and Camunda Modeler.
      41
      -
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants and other tools to create, edit, import, and export BPMN 2.0 workflow diagrams, including through a local browser-based live modeler with explicit save back to the session.
      11
      MIT