appkit-bpmn-server

An MCP Apps-compliant server that generates, edits, and manages BPMN 2.0 diagrams from natural language — powered by LLMs.

Describe a business process in plain text and get a valid, layouted BPMN diagram with an interactive viewer rendered inline in any MCP Apps-capable host (Claude, ChatGPT, VS Code, etc.).

Features

• Natural language to BPMN — Generate process diagrams from text descriptions
• Interactive viewer — Built-in bpmn-js editor with zoom, pan, and editing capabilities
• Update diagrams — Modify existing diagrams via follow-up prompts without starting over
• Persistent storage — SQLite-backed diagram storage with Alembic migrations
• User assignment — Associate diagrams with specific users via x-user-id header or query parameter (defaults to -1)
• Auto-layout — Automatic swimlane arrangement and edge routing
• Validation — Generated BPMN XML is validated before storage
• MCP Apps UI — Inline rendering in any compliant chat host

Architecture

MCP Host (Claude, ChatGPT, …)
  │
  │  MCP over HTTP (stateless)
  ▼
appkit-bpmn-server      ← this repo (configuration + startup)
  │
  ├─ appkit-mcp-bpmn    ← MCP tools, viewer, BPMN generation
  ├─ appkit-commons     ← shared config, OpenAI client, registry
  └─ SQLite database    ← diagram persistence

Prerequisites

• Python 3.14+
• uv package manager
• An OpenAI-compatible API key (Azure OpenAI or OpenAI)

Getting Started

1. Clone and install

git clone https://github.com/jenreh/appkit-bpmn-server.git
cd appkit-bpmn-server
uv sync

2. Configure environment

Create a .env file in the project root:

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://your-endpoint.openai.azure.com/v1

3. Run database migrations

uv run alembic upgrade head

4. Start the server

uv run appkit_bpmn_server

The MCP endpoint will be available at http://127.0.0.1:8000/mcp.

5. Connect from an MCP client

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "bpmn": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

MCP Tools

Tool	Description
new_bpmn_diagram	Generate a new BPMN diagram from a natural language description
update_bpmn_diagram	Modify an existing diagram using a follow-up prompt
save_bpmn_diagram	Save pre-built BPMN XML
get_bpmn_xml	Retrieve the BPMN XML for a diagram (app-only)
save_or_update	Persist edits made in the viewer (app-only)
rename_bpmn_diagram	Rename a diagram (app-only)

Tools marked app-only are hidden from the model and callable only from the interactive viewer.

Configuration

Server settings are in configuration/config.yaml:

app:
  mcp_bpmn:
    storage_mode: database          # database, filesystem, or both
    default_model: gpt-5.3-codex    # LLM model for generation
    max_file_size_mb: 10
    diagram_types:
      - process

User Assignment

Diagrams can be associated with a specific user by sending an x-user-id value. This can be provided as:

• HTTP header: x-user-id: 123
• Query parameter: ?x-user-id=123

If neither is provided, the user ID defaults to -1.

Project Structure

├── configuration/
│   ├── config.yaml          # Development configuration
│   ├── config.prod.yaml     # Production overrides
│   └── logging.yaml         # Logging configuration
├── alembic/                 # Database migrations
├── src/
│   └── appkit_bpmn_server/
│       └── main.py          # Server entry point
├── pyproject.toml
└── .env                     # API keys (not committed)