bizagi-modeler
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bizagi-modeler Generate a BPMN diagram for our invoice approval process and preview it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
bizagi-mcp
Turn a description of a process into a BPMN 2.0 diagram that opens cleanly in Bizagi Modeler.
An MCP server that generates, reads, audits and previews BPMN 2.0 diagrams — and drives the Bizagi Modeler desktop app on Windows.

Generated from a 60-line JSON spec. Every coordinate above was computed, not placed by hand.
Why this exists
Bizagi Modeler has no scripting API. The one integration path it does support is the open BPMN 2.0 XML format, through its Export / Import tab.
But there is a catch that makes naive generation useless: Bizagi imports the coordinates written in the file verbatim. It does not lay out a diagram for you. Emit a structurally perfect BPMN file without geometry and it opens as a pile of boxes stacked on the origin.
So the hard part of this server is not the XML. It is the layout.
Related MCP server: MCP-BPMN Server
What it does
Tool | What it does |
| The spec format: every node type, field and rule |
| Description → a |
| Edit an existing |
| Parse a |
| Scan a folder and summarise each BPMN file |
| Audit against BPMN 2.0 rules and modelling conventions, with a fix for each finding |
| Render to SVG — check the result without opening Bizagi |
| Process documentation as Markdown (outline + audit) |
| Whether Bizagi Modeler can be driven from here |
| Launch Bizagi Modeler, optionally with a file |
| Drive Export / Import ▸ BPMN, and verify that it landed |
| Drive Export ▸ BPMN for the open diagram |
The first eight are pure Python and run on any OS, with or without Bizagi installed.
Only the four bizagi_* tools need Windows.
The layout engine
A lane-aware layered layout, in the order it runs:
Break cycles so the graph can be layered at all
Longest-path layering → each node's horizontal column
Barycenter ordering per (column, lane) → fewer crossing lines
Adaptive lane heights, sized to the tallest cell each band holds
Reserved strips — a bypass band along the top of any lane carrying a column-skipping branch, and a channel strip at the bottom for loop-backs
Orthogonal routing that goes around obstacles rather than through them
Label separation as a final pass
What it guarantees
These are not aspirations. Each one is a test that fails when the rule is removed:
No two shapes overlap
No edge is drawn through a shape that is not its own endpoint
Every element sits inside its pool
Message flows run in the empty corridor between pools, never horizontally through one
Each message flow gets its own line in that corridor, and the corridor is sized from how many flows cross it — so their labels do not stack
Loop-backs each get their own channel in a strip reserved while lanes are sized
A branch that skips columns detours inside its own lane, over the activities it skips
A gateway's branches leave from visibly different points, so a two-way split does not read as a single arrow
Boundary-event flows leave downwards, never back up through the host activity
Annotations and data stores sit beside what they describe — or, when they have no association, inside the pool they declare rather than off the canvas
No label is written over another label or over a shape
Design notes
A few decisions that are easy to get wrong:
A label is as wide as its text. Reserving a flat box for every label makes collisions between the long ones invisible to anything that measures the reserved box.
Reserved space must be held out of centring. Grow a lane to make room for a channel and then centre the shapes in it, and half the new space is handed back as padding above — the channel ends up too thin to use.
A detour belongs in the gaps between shapes, not around all of them. Routing over or under everything lands the line outside the pool, and the verticals that reach it then cross every lane on the way.
A data store can be associated with many activities but sits beside one. Placing it once per association leaves holes in the lanes where the earlier placements were.
Install
pip install -e .For the Windows desktop tools:
pip install -e ".[desktop]"Python ≥ 3.10.
Register with Claude
claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"bizagi-modeler": {
"command": "bizagi-mcp",
"env": {
"BIZAGI_MCP_ROOT": "C:\\Users\\you\\Documents\\Bizagi"
}
}
}
}If bizagi-mcp is not on PATH:
{
"mcpServers": {
"bizagi-modeler": {
"command": "python",
"args": ["-m", "bizagi_mcp.server"],
"env": { "BIZAGI_MCP_ROOT": "C:\\Users\\you\\Documents\\Bizagi" }
}
}
}For Claude Code: claude mcp add bizagi-modeler -- bizagi-mcp
Environment variables
Variable | What it does |
| Confine every file read and write to this folder. Strongly recommended. |
| Full path to |
Usage
Generate a diagram
"Model a leave request: the employee submits it, the manager approves or rejects it, HR records the outcome. Save it to
D:\Processes\leave.bpmn."
Then in Bizagi Modeler: Export / Import ▸ Import ▸ BPMN.
Analyse an existing model
Export from Bizagi first (Export / Import ▸ Export ▸ BPMN), then:
"Read
D:\Processes\purchasing.bpmn, walk me through it, and tell me what is wrong with it."
Example
See examples/purchase_request.json (the spec), .bpmn (generated) and .svg (preview).
Validation rules
Structure (BPMN001–BPMN020, severity error / warning)
Missing start or end events · unreachable elements · dead ends · sequence flows crossing pools · message flows inside one pool · gateways branching without conditions · event-based gateway targets · implicit split and merge · boundary events on non-activities · duplicate ids · a default flow that also carries a condition · one-in-one-out gateways.
Conventions (BP001–BP017, severity warning / info)
Activity naming (verb + object) · gateways not phrased as questions · unlabelled branches · documentation coverage · pools without lanes · empty lanes · diagram size · duplicate names · pools that never exchange messages.
Every finding names the offending element and the concrete step to fix it.
Driving the desktop app
bizagi_open is the dependable path: Modeler takes a file as a command line argument,
so no menu has to be driven.
bizagi_import_bpmn drives the ribbon, and is honest about it:
It claims the foreground and verifies it got there. Windows refuses
SetForegroundWindowto a process that does not own the foreground, andset_focus()returns as if it worked — clicking on regardless sends a real mouse click into whatever the user is working in.It counts diagram tabs before and after, and reports
imported: true/falsefrom that evidence rather than from hope.Both counts are taken with the window raised, because a window that is behind can hand back an incomplete accessibility tree.
There is no background mode
Import cannot run while the machine is used for something else. Three routes were tested against Modeler 4.3.0.008 and all three are closed:
Route | Result |
UI Automation | Ribbon tabs expose no patterns at all |
| Ignored, across every candidate window handle |
| Exits 0 without importing anything |
The ribbon only responds to real mouse input on a focused window. For unattended runs, give Bizagi its own Windows session or VM. If you want that recorded so nobody retries it: this table is the record.
Security
Paths are fully resolved (
~,.., symlinks) before being checked, then confined toBIZAGI_MCP_ROOTwhen it is setXML parsing goes through
defusedxmlwhen available (XXE, billion laughs)Files are never overwritten without
overwrite=trueBizagi is launched with an argument list and no shell, so a filename can never become a command
Every error comes back as data (
{"ok": false, ...}), never a traceback
Tests
pip install -e ".[dev]"
pytest -q72 tests: spec normalisation, XSD element ordering, BPMNDI completeness, every layout guarantee listed above, label collisions, round-trips, each validation rule, path traversal, ribbon button selection, foreground verification, and the error contract of every tool.
Known limitations
.bpmis not read. It is Bizagi's proprietary format; export to BPMN first.list_processesstill lists.bpmfiles and flags them.Desktop control is Windows-only and needs
pywinauto.Diagrams are generated one level deep. A sub-process appears as a collapsed shape; its contents are not generated.
Layout tidiness is guaranteed for the geometry written to the file. Bizagi places node names by its own rules, which the diagram interchange section does not control.
License
MIT — see LICENSE.
Available Tools
12 toolsbizagi_export_bpmnA
Drive File ▸ Export ▸ BPMN for the diagram currently open in Bizagi Modeler, so it can then be read and audited by the other tools.
Best-effort UI automation; confirm the dialog on screen if nothing appears.
Args: output_path: Where Bizagi should write the .bpmn file.
Inputs: output_path (required). Returns: object
bizagi_import_bpmnA
Drive Bizagi Modeler's File ▸ Import ▸ BPMN dialog for a .bpmn file.
Best-effort UI automation: ribbon shortcuts differ between Modeler versions. If it does not take, import the file by hand — it is already on disk.
Args: file_path: The .bpmn file to import.
Inputs: file_path (required). Returns: object
bizagi_openA
Open Bizagi Modeler, optionally with a .bpm or .bpmn file.
This is the dependable desktop action — the file is passed on the command line rather than through a menu.
Args: file_path: Diagram to open. Leave empty to just start the application.
Inputs: file_path. Returns: object
bizagi_statusA
Report whether Bizagi Modeler can be controlled from here: platform, whether pywinauto is installed, where BizagiModeler.exe is, whether it is running, and which document is open. Call this before the other bizagi_* tools.
Inputs: no named parameters. Returns: object
create_processA
Generate a BPMN 2.0 diagram from a process specification and write it as a .bpmn file that Bizagi Modeler can import (File ▸ Import ▸ BPMN).
Shape positions are computed automatically with a lane-aware layered layout, so the imported diagram is readable rather than a heap of overlapping boxes. The result includes an audit of the generated model.
Args: spec: The process definition. Call get_spec_reference() for the format. output_path: Where to write the .bpmn file. Leave empty to only preview. overwrite: Replace output_path if it already exists. return_xml: Include the full XML in the response (large).
Inputs: spec (required), overwrite, return_xml, output_path. Returns: object
export_documentationA
Produce a Markdown process document from a .bpmn file: an outline of every pool and lane, the step-by-step flow, and optionally the audit findings.
Args: file_path: The .bpmn file to document. output_path: Where to write the .md file. Leave empty to return the text only. include_audit: Append the audit report. overwrite: Replace output_path if it exists.
Inputs: file_path (required), overwrite, output_path, include_audit. Returns: object
get_spec_referenceA
Show the specification format that create_process expects, with every node type, field, and modeling rule. Read this before writing a spec for the first time.
Inputs: no named parameters. Returns: result
list_processesA
Find BPMN and Bizagi files in a folder, with a one-line summary of each .bpmn (pools, activities, gateways).
Args: directory: Folder to scan. recursive: Include sub-folders.
Inputs: directory (required), recursive. Returns: object
read_processA
Read a .bpmn file and return its structure: pools, lanes, activities, gateways, events, and the flows between them.
Note: Bizagi's native .bpm format is proprietary and cannot be read here. Export it first from Bizagi Modeler (File ▸ Export ▸ BPMN).
Args: file_path: Path to a .bpmn or .xml file. detail: "summary" (structured JSON), "outline" (readable walk-through), or "spec" (an editable specification you can pass back to create_process).
Inputs: file_path (required), detail. Returns: object
render_previewA
Draw the diagram as an SVG so it can be checked without opening Bizagi Modeler — same geometry the .bpmn carries, so what you see is what imports.
Args:
file_path: A .bpmn file to preview. Mutually exclusive with spec.
spec: A specification to preview before writing it anywhere.
output_path: Where to write the .svg. Leave empty to return the markup.
overwrite: Replace output_path if it exists.
Inputs: spec, file_path, overwrite, output_path. Returns: object
update_processA
Edit an existing .bpmn file by merging changes into its specification and regenerating the diagram (with a fresh layout).
changes accepts the same keys as a spec. Lists are handled by key:
a node or flow whose id matches an existing one replaces it, anything else
is appended. Use "removeNodes": ["id", …] / "removeFlows": ["id", …] to delete.
Args: file_path: The .bpmn file to edit. changes: Partial specification to merge in. output_path: Where to write the result. Defaults to overwriting file_path. overwrite: Required when writing over an existing file.
Inputs: changes (required), file_path (required), overwrite, output_path. Returns: object
validate_processA
Audit a diagram against BPMN 2.0 correctness rules and modeling conventions, and return every finding with a concrete fix.
Checks include: missing start/end events, unreachable elements, dead ends, sequence flows crossing pools, message flows inside one pool, gateways that branch without conditions, event-based gateway targets, implicit splits, boundary events on non-activities, plus naming, documentation, lane and diagram-size conventions.
Args:
file_path: A .bpmn file to audit. Mutually exclusive with spec.
spec: A specification to audit before generating it.
include_best_practice: Include convention findings, not only errors.
format: "json" for structured findings, "markdown" for a report.
Inputs: spec, format, file_path, include_best_practice. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct action: file discovery, spec reference, create, update, read, validate, preview, documentation, and Bizagi desktop automation. The only mild overlap is preview capability between create_process and render_preview, but their outputs and intended use are clearly differentiated.
Most tools follow a clear verb_noun pattern, and the desktop automation tools consistently share the bizagi_ prefix. The minor deviation is bizagi_status, which is a noun phrase rather than verb-first, and get_spec_reference uses get while similar operations use read; still, the overall pattern is predictable.
Twelve tools is well-scoped for a BPMN modeling server. Each tool covers a meaningful part of the workflow without unnecessary redundancy, and the count is comfortably within the typical 3-15 range.
The toolset covers the full modeling lifecycle: discovery, creation, editing, reading, validation, preview, documentation, and desktop import/export. The only noted limitation—reading proprietary .bpm files—is documented with a practical workaround rather than an untooled dead end.
Related MCP Connectors
Free BPMN 2.0 validator: send BPMN XML, get errors and warnings. Anonymous, nothing stored.
Turn conversations about work processes into process maps: read, draw, correct and export.
Manage SysML2 projects; check, evaluate, verify, query, document and diagram models.
Generate, validate and read EN 16931 and Peppol BIS 3.0 e-invoices, in UBL and CII.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to create, manipulate, and manage BPMN 2.0 diagrams programmatically, with support for Mermaid conversion, auto-layout, and file persistence.2415MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to create and manage one BPMN 2.0 diagram at a time, including Mermaid conversion, validation, layout, persistence, and XML or SVG export.27760 npmMIT
- FlicenseCqualityBmaintenanceEnables 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-
- AlicenseAqualityCmaintenanceEnables AI assistants to create and edit valid BPMN 2.0 diagrams with automatic layout, validation, and export to XML, SVG, PNG, and other formats. Supports HTTP deployment with token-based authentication and session-isolated diagram handling.20MIT