loonflow 3.0: a Django workflow engine with drag-and-drop design and an MCP ticket server

What loonflow solves, and who ends up running it

Most teams that need approvals already have a tracker. What they do not have is a place where the approval path itself is a first-class object: versioned, editable by a non-developer, and callable over an API. loonflow targets that gap. The README describes it as an "enterprise-grade unified workflow solutions" platform and lists IT operations, HR approvals, financial reimbursements and customer service as the ticket types it is meant to cover. The primary language of the repository is TypeScript, which reflects the React 18 and MUI 5 frontend, while the engine itself is Django 5.2 on Python 3.12. That split matters when you plan who maintains it. A backend developer owns the process engine and hooks; a frontend developer owns the designer and form builder. If you have neither, the docker-compose deployment will get you running but not extended. The project also offers a managed SaaS edition with a two-week free trial, so the honest framing is that loonflow is for organizations that want the engine on their own infrastructure and are willing to pay that cost in operations.

How the process engine, hooks and MCP server fit together

Three layers are visible from the repository layout and the README. The first is the design layer: a drag-and-drop process designer with conditional branches, parallel tasks and hooks, plus a form designer with field types including text, numbers, dropdowns, personnel selection and attachments. The README states that process logic validation runs during design, and that you can configure multiple versions of a process and switch between them for testing. The second layer is the extension framework. The README says plugins are available for "almost all key nodes", naming custom actions, permission validation and notification methods. Permission checks can be scoped by role, department or business condition. The third layer is integration: RESTful APIs for external systems, and a Model Context Protocol server advertised under the name loonflow-ticket. That server exposes tools including ticket_list, ticket_detail, ticket_prepare_handle, ticket_handle and user_list. The README notes that ticket_handle supports a dry_run validation parameter, which is the detail worth pausing on: an AI client can prepare a state change and have it checked before committing. Tools reuse the same permission-aware ticket services as the web UI, so an MCP client does not get a privilege shortcut.

Installing loonflow with docker-compose and logging in

The README gives a four-step deployment. First, download the compose file and the environment file from the repository's docker_compose_deploy directory.

wget https://raw.githubusercontent.com/blackholll/loonflow/refs/heads/master/docker_compose_deploy/docker-compose.yml
wget https://raw.githubusercontent.com/blackholll/loonflow/refs/heads/master/docker_compose_deploy/.env

The README's only guidance on the .env file is to modify at least the password section, so treat the rest of the file as something to read before you start rather than accept. Then bring the stack up from the directory that holds the compose file.

docker-compose up -d

Once the containers are up, you log in with the email and password you set in .env. That is the whole documented path. There is no documented migration command, no documented way to seed an initial admin beyond the .env credentials, and no documented upgrade procedure for moving an existing database between releases. The README points to https://loonflow.readthedocs.io for installation, configuration and usage detail, so the compose file is a starting point and the docs are where the operational questions get answered. If you are evaluating rather than deploying, the SaaS edition avoids all of this.

Connecting an MCP client to the ticket server

The MCP section is the part of loonflow that is genuinely different from a conventional workflow tool, and it is also the part with the most operational detail in the README. Authentication uses a personal access token, whose values start with the prefix lfpat., or a JWT issued by loonflow. You create a personal access token in the product UI under Personal Information, then Personal Access Token. The hosted endpoint is https://mcp.loonflow.com/mcp. For a self-hosted install, the README says the MCP process serves Streamable HTTP on the path /mcp by default, and that host, port and transport are adjusted through environment variables described in the documentation. The README does not list those variable names, so you will need the MCP guide at loonflow.readthedocs.io before you can point a client at your own instance. What the README does confirm is the tool surface: listing, inspecting, preparing and handling tickets, plus paginated user search within the authenticated tenant. The dry_run parameter on ticket_handle is the safety valve here. Wire an AI assistant to a ticket system without a validation step and you have given it write access to your approval queue.

Where loonflow is the wrong choice

The licence is the first constraint. loonflow is AGPL-3.0. If you modify it and expose it to users over a network, the AGPL's network clause is the thing your legal team will want to read, and this article cannot tell you what it means for your product. The README also states that multi-tenant support, which provides data isolation for SaaS providers and large enterprise groups, requires additional authorization. That is a commercial boundary inside an open source project, and it is worth confirming before you design a multi-tenant deployment around it. The second constraint is the deployment model itself. Everything documented here is a self-hosted Django stack behind docker-compose. There is no documented serverless or embedded mode. If your team has no one who can run a Django application, the SaaS edition exists precisely because that is a real gap. The third constraint is documentation depth. The README covers installation in four steps and then defers to Read the Docs for configuration, hooks and the API. The Postman collection is linked for API reference. For a project at release r3.2.2, that is a reasonable split, but it means you cannot judge the extension framework from the repository alone. Read the hook development guide before you promise a custom action to anyone.

loonflow against building on a general-purpose workflow library

The realistic alternative is not another ticket system. It is assembling the same capability from a BPMN library or a general workflow engine and writing the ticket, form and permission layers yourself. The difference in approach is where the abstraction sits. A BPMN library gives you a process definition format and an execution engine, and leaves the ticket model, the form schema, the assignee rules and the audit trail to you. loonflow starts from the ticket: it ships the form designer, the multi-type ticket support, the audit log and the permission model as part of the product, and treats the process definition as something a non-developer edits in a browser. That is a real trade. You get a working approval system sooner, and you inherit loonflow's data model and its React frontend. If your process logic is unusual enough that the visual designer's node set does not express it, you are writing hooks against loonflow's extension points rather than against a neutral engine. The README's claim that plugins cover "almost all key nodes" is the claim to test during evaluation, because that sentence is doing a lot of work.

Maintenance, releases and what the AGPL asks of you

The last push to the repository was on 2026-05-25, which is the same timestamp as release r3.2.2. Releases r3.2.0, r3.2.1 and r3.2.2 landed within May 2026, roughly three weeks apart, so the release cadence in that window was steady. The repository is not archived. Beyond that, the repository does not document a support policy, a long-term release branch or an upgrade path between versions, and the README's installation section stops at first login. That is the practical upgrade cost: you are tracking a moving Django and React application, and the compose file pins images you will need to refresh deliberately. On licensing, AGPL-3.0 is a copyleft licence with a network-use clause, and the README separately flags multi-tenant data isolation as requiring additional authorization. Whether your deployment triggers those obligations depends on facts about your organization that are not in this repository, so route the question to counsel rather than to a README. The commercial support contact in the README is the route for enterprise customization and deployment help.

Editorial conclusion

Adopt loonflow if you need a self-hosted ticket and approval engine with a visual designer and you are comfortable with the AGPL-3.0 obligations and a Django deployment. Skip it if you want a hosted service with no operational work, or if your process logic changes faster than you can redeploy. Verify first that the docker-compose .env covers your database and mail settings, that multi-tenant isolation is licensed for your case, and that your MCP client can authenticate with an lfpat. token against /mcp.

Frequently asked questions

Official sources

1. blackholll/loonflow on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases