MCP-BPMN Server

A Model Context Protocol (MCP) server that enables AI agents to create, manipulate, and manage BPMN 2.0 (Business Process Model and Notation) diagrams programmatically.

🎯 Overview

MCP-BPMN provides a standardized interface for AI assistants to work with business process diagrams. It generates valid BPMN 2.0 XML files that can be viewed and edited in any BPMN-compliant tool (VS Code BPMN Editor, Camunda Modeler, etc.).

Key Features

• ✅ Complete BPMN 2.0 Support: Events, activities, gateways, pools, and sequences
• ✅ Mermaid to BPMN Conversion: Bootstrap BPMN diagrams from Mermaid flowcharts
• ✅ Smart Auto-Layout: Automatic positioning with branch handling for gateways
• ✅ File Persistence: Save diagrams locally for editing in visual tools
• ✅ Proper Visual Rendering: Accurate waypoint calculation for connections
• ✅ Enterprise-Ready: Clean API design following BPMN standards
• ✅ No Browser Dependencies: Server-side XML generation

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/your-org/mcp-bpmn.git
cd mcp-bpmn

# Install dependencies
npm install

# Build the project
npm run build

# Run tests (optional)
npm test

Configuration

For Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-bpmn": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-bpmn/dist/server/index.js"]
    }
  }
}

For Other MCP Clients

Use the compiled CommonJS bundle:

node dist/server/bundle.cjs

📚 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.

Creation Tools

new_bpmn

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

{
  name: "Order Processing",
  type: "process" // or "collaboration" (optional, defaults to "process")
}

new_from_mermaid

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

{
  name: "My Process",
  mermaidCode: "graph TD\n  A[Start] --> B[Task] --> C[End]"
}

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"
}

save

Save the current diagram to its file (requires filename to be set).

{}

save_as

Save the current diagram with a new filename.

{
  filename: "my-process.bpmn"
}

close