BPMN MCP Editor

Version 0.1.0 · Early release

A Camunda 7 BPMN editor you can use in the browser and drive from AI agents over the Model Context Protocol (MCP). The web UI is built on bpmn.io (palette, properties panel, Camunda extensions). Agents edit the same diagrams through structured MCP tools—not raw XML. Browser and agent share one database, with optimistic locking so the canvas stays consistent.

Features

• Browser modeler — Full BPMN editing with Camunda 7 fields via bpmn-js and the properties panel.

• MCP server — stdio (e.g. Cursor) or HTTP; semantic operations (add_elements, connect_elements, update_element, delete_element, batch_edit, and more).

• Shared state — Changes from the agent appear in the browser (polling); user edits and agent locks are coordinated.

• Validation — build profile while designing; stricter deploy profile for Camunda 7 readiness (start/end events, labels, historyTimeToLive, etc.).

• Auto-layout — Optional layout pass for readable diagrams.

• SQLite by default — PostgreSQL supported for production-style setups.

Related MCP server: MCP-BPMN Server

How it works

┌─────────────┐     REST / SSE      ┌──────────────────┐     Prisma      ┌──────────┐
│  Web UI     │ ◄──────────────────►│  Hono API        │ ◄──────────────►│ SQLite / │
│  (Vite)     │                     │  + MCP (HTTP)    │                 │ Postgres │
└─────────────┘                     └────────▲─────────┘                 └──────────┘
                                             │
                                    stdio MCP │ (Cursor, CLI)
                                             │
                                      ┌──────┴──────┐
                                      │ AI agent    │
                                      └─────────────┘

1. You run the dev or production server (API on port 3001, web UI on 5173 in development).

2. The browser loads processes from the API and saves user edits with revision checks.

3. An MCP client connects via stdio or HTTP and uses tools such as create_process, acquire_lock, and batch_edit.

4. While an agent holds a lock, the canvas is read-only in the browser; locks expire after inactivity.

On first start, a sample process Invoice approval is seeded in the database.

Requirements

• Bun (runtime and package manager)

• Modern browser for the editor

Quick start

bun install
bun run dev

Production:

bun run build
bun run start

MCP configuration

stdio (Cursor, project root)

{
  "mcpServers": {
    "bpmn": {
      "command": "bun",
      "args": ["src/server/stdio.ts"]
    }
  }
}

The same configuration is available in .cursor/mcp.json. The web server must be running for agent changes to show up in the browser; the UI polls the database about once per second.

HTTP

If the agent talks directly to the running server:

http://127.0.0.1:3001/mcp

Optional: set MCP_API_KEY and send Authorization: Bearer <key> on HTTP MCP requests.

Agent editing model

Agents work with short, typed operations, not free-form BPMN XML:

create_process acquires a lock and returns lockToken plus revision. Every mutating call needs both. If the revision is stale or the result would be invalid BPMN, nothing is committed.

Locking: While locked, the canvas is read-only. A recent user edit blocks a new agent lock for a few seconds. The lock expires after 45 seconds without further agent mutations.

Validation: validate_process with profile: "deploy" checks Camunda 7 deploy readiness. During construction, profile: "build" is looser (e.g. missing end events may be warnings); a service task without implementation is still an error.

Database

Default: SQLite at data/dev.db.

PostgreSQL:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/bpmn_editor bun run db:setup

db:setup switches the Prisma provider to postgresql and applies the schema. Restart the server afterward.

Environment variables

Scripts

Third-party notices

This application bundles many open-source libraries (MIT, Apache-2.0, BSD, ISC, and others). Notable obligations:

• bpmn-js (MIT) — The bpmn.io watermark in rendered diagrams must not be removed or obscured.

• Geist (OFL-1.1) via @fontsource-variable/geist — Keep font license notices when redistributing builds.

A full THIRD-PARTY-NOTICES file is recommended before public distribution.

License

BPMN MCP Editor is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0).

You may use, modify, and redistribute this software for any purpose, including commercial use, as long as you comply with the AGPL. In particular:

• If you distribute copies or modified versions, you must provide corresponding source under the same license.

• If you modify this program and run it on a server so users interact with it over a network (for example, a hosted editor or HTTP MCP endpoint at /mcp), you must offer those users the corresponding source of your version (AGPL section 13).

Redistribution and commercial hosting are allowed under these terms; they are not a substitute for a separate commercial license if you need terms outside the AGPL.

Dependency compliance (summary)

Production dependencies are overwhelmingly MIT, ISC, Apache-2.0, and BSD. When you distribute this application, preserve third-party copyright notices and honor bpmn-js (watermark) and font attribution requirements. See Third-party notices above.

Disclaimer

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

BPMN diagrams and process definitions created with this tool are your responsibility. This project is not affiliated with Camunda GmbH. Camunda 7 compatibility is best-effort via community tooling (camunda-bpmn-moddle, lint plugins); always validate in your target environment before production deployment.

Nothing in this README constitutes legal advice. Have qualified counsel review licensing before public release.

Contributing

Contributions are welcome once the repository is public. Please open an issue before large changes. Run bun run test and bun run typecheck before submitting a pull request.

Status

v0.1.0 is an early release: APIs, MCP tools, and database schema may change. Use in production at your own risk.