BA BPMN plugin

Draw checked BPMN diagrams from a chat. You describe a process in plain words; the assistant asks only what is missing, shows a picture, and after you approve gives you an SVG, a PNG and a .bpmn file that opens in Camunda.

Works in Claude, Codex and Antigravity. One engine, one set of skills, three thin wrappers.

How it works

What a business analyst sees. They describe a process in plain words. The assistant asks only what is missing, shows a picture for review, redraws it when asked, and writes the files once the picture is approved.

Diagram source: docs/diagrams/how-it-works-ba.mmd, drawn with Pele.

What is inside. Each AI tool only reads the same skills and starts the same small server. All the drawing happens in one engine on the user's own computer. Nothing is uploaded.

Diagram source: docs/diagrams/how-it-works-inside.mmd, drawn with Pele.

Three things make it safe to rely on:

1. The description is data, never code. Only listed fields are accepted, and nothing in it is ever run.

2. Every picture is checked before anyone sees it. The engine reports overlaps, crossed lines, missing ends and more, and the assistant fixes them first.

3. The Camunda file is tested too. The .bpmn is loaded in Camunda's own viewer before the export is reported as done.

Related MCP server: MCP-GLSP

What is in this folder

Install

Status: these commands follow each tool's documentation and the draw.io plugin, but none has been run in the real tool yet. See "What has been tested, and what has not" below.

You need uv (a small helper that runs Python programs) and Chrome or Edge (for the PNG and the Camunda check).

Then start a new chat and say "set up the BPMN tools" (or use the bpmn-setup shortcut, for example /ba-bpmn:bpmn-setup), and describe a process.

How the server starts differs: Claude runs it from the plugin's own folder (${CLAUDE_PLUGIN_ROOT}). Codex installs a self-contained copy of its folder and Antigravity documents no folder variable, so both run uvx --from <source> bpmn-mcp, with the source set in packaging.json.

What it needs on the computer

• uv (or Python 3.10+ with pip install .)

• Chrome or Edge, only for the PNG and the Camunda import check. Set BPMN_BROWSER if it is not found, and BPMN_BROWSER_ARGS to give it extra flags (for example --no-sandbox on a locked-down Linux machine).

What has been tested, and what has not

What it draws

Start and end events (an end can be an error), intermediate catch events, boundary timer, message and error events; user, service, send, receive, manual and script tasks with their type icons; collapsed sub-processes; decision, parallel and inclusive gateways; pools, lanes, message flows, link connectors, annotations. Not yet: event-based and complex gateways, expanded sub-processes, signal and escalation events, data objects, loop and multi-instance markers.

Privacy

Files are written on your own computer, under the folder the assistant was started in. Nothing is uploaded.

Security

To report a problem privately, see SECURITY.md.

What is checked, so you do not have to take it on trust:

• Every change runs the same checks and the whole test suite on Linux and Windows (.github/workflows/check.yml).

• CodeQL, GitHub's code scanner, reads the Python, JavaScript and workflow files on every change and every week.

• OpenSSF Scorecard grades the repository's habits every week. The results are in the repository's Security tab and are not published anywhere else.

• Dependabot proposes dependency updates weekly. Secret scanning and push protection are on.

• GitHub Actions are pinned to full commit ids, the workflows have read-only access, and the server the Codex and Antigravity plugins start is pinned to the release tag of the version you install.

Develop

pip install -e ".[test]"
pytest --cov=bpmn_mcp.spec --cov=bpmn_mcp.server
python scripts/sync_plugins.py          # after editing skills/ or packaging.json
python scripts/sync_plugins.py --check  # fails if the host folders drifted
python scripts/prepublish.py --preview  # every check before publishing, and a preview of the README
python scripts/prepublish.py --install-hook  # once per clone: run the checks before every git push

Known limits and open items

• Not yet run in the real tools. The Claude, Codex and Antigravity installs, and uvx start-up, have not been tried on a clean Windows laptop. The plugin formats were checked against the draw.io plugins and the Codex checks of sebahrens/bpmn-mcp, not against a running Codex or Antigravity.

• Headless Edge or Chrome hangs now and then (about 2 in 15 calls in testing). The engine retries once.

• The bundled bpmn-js viewer is used unmodified under the bpmn.io licence. See THIRD_PARTY_NOTICES.md.

• Maintainers: see AGENTS.md for the release steps and docs/TRAPS.md for known pitfalls.