You can ask Claude to write a Confluence page and get back a finished page with rendered Mermaid diagrams in it, instead of a block of diagram code that someone still has to turn into a picture.
The manual step after AI drafts a page
Many teams already draft documentation with AI. You describe a process, Claude writes the explanation, and it usually adds a Mermaid diagram, because Mermaid is plain text and language models write it well.
Then the manual part starts. Someone creates the page, pastes the text, inserts a diagram macro, copies the Mermaid code into it and checks that it renders. If the assistant creates the page itself, the diagram often lands as a plain code block: lines of flowchart TD and arrows instead of a picture.
For one page that takes a few minutes. Across a team that documents every service, process change and incident, the diagram step is the one that gets skipped.
What happens when you ask
With Mermaid Diagrams Macro for Confluence and Secure MCP for Confluence installed, you describe what you need once and Claude creates the whole page: headings, explanation, and diagrams that render the moment the page opens.
- You ask Claude for a page, for example how an order moves through checkout, with a diagram of the steps.
- Claude calls Secure MCP, which runs as a Forge app on your Confluence site and acts with your own Confluence permissions. Secure MCP itself sends no content outside Atlassian Confluence and Forge. The page content Claude reads or writes goes to the AI tool you connect, as with any assistant.
- Claude creates the page and puts the Mermaid source straight into a Mermaid Diagrams macro instead of pasting it as text.
- The macro renders the diagram as SVG. Readers can open it full screen, zoom in up to 10x and export it as PNG or SVG. It also renders for guests and anonymous viewers if your space is public.
The result is a normal macro on a normal Confluence page. Your team edits it like any other diagram. If Claude writes Mermaid with a syntax error, the macro shows an error message instead of a broken picture, and you ask Claude to fix it in the same chat.
Setup
A Confluence admin does the first two steps once. Each person then connects their own AI tool.
- Install Mermaid Diagrams Macro for Confluence. It renders Mermaid code as diagrams and supports 16 diagram types, from flowcharts and sequence diagrams to Gantt charts, ER diagrams and mind maps.
- Install Secure MCP for Confluence and set its scope. In the app's admin settings you choose which spaces AI tools can reach, exclude others or add a CQL filter, and turn off whole groups of tools, such as creating pages or adding comments.
3. Connect your AI tool. In Confluence, open Apps → Connect MCP, choose read & write access, and generate a token. The page gives you a ready-to-paste snippet for your tool. Supported tools include Claude Code, Claude Desktop, Cursor, VS Code, Windsurf and Codex CLI.
On a large site, start small. Limit Secure MCP to one or two pilot spaces so AI tools can reach nothing else, let the team that owns those spaces work with it for a couple of weeks, review the audit log, then widen the scope.
Four prompts to try
Start each prompt with a link to the Create pages with AI guide. It tells the assistant how to build the diagram macro. Without it, assistants tend to paste the code as text. Teams on Claude Code can put the link in their CLAUDE.md so nobody has to remember it.
A process page
Use this guide: https://docs.apportunity.xyz/mermaid-diagrams/create-pages-with-ai
Create a Confluence page in the DEV space called "Checkout flow" that explains how an order moves from cart to confirmation, with a diagram of the steps.
The result:
An architecture page
Use this guide: https://docs.apportunity.xyz/mermaid-diagrams/create-pages-with-ai
Create a page in the ARCH space called "Notification service". The service has four parts: an API that receives events, a queue, a worker that picks the channel, and senders for email, SMS and push. Explain each part in a short section and add one diagram of how they call each other.
The result:
An update to an existing page
Use this guide: https://docs.apportunity.xyz/mermaid-diagrams/create-pages-with-ai
Update the "Checkout flow" page in the DEV space: add the new fraud check between payment and confirmation, in both the text and the diagram.
The result:
A page with several diagrams
Use this guide: https://docs.apportunity.xyz/mermaid-diagrams/create-pages-with-ai
Create a release process page in the OPS space with three sections: planning, testing and rollout. Give each section its own explanation and diagram. Use a Gantt chart for the rollout, and send me the link when it's done.
The result:
Tips and limits
A few habits make the first result usable more often:
- Name the target space by its name or key.
- Ask for an explanation as well as a diagram. The text is what makes the picture useful to the next reader.
- Name the diagram type when it matters: sequence for calls between systems, Gantt for timelines, flowchart for decisions.
- Open the page right away and ask for corrections in the same chat.
One limit matters if you want AI to keep diagrams current. Claude can update a diagram as often as you like until someone edits that diagram by hand in Confluence. After a manual edit, readers keep seeing the hand-edited version, and later changes from Claude no longer show. So decide per page who maintains the diagram: the AI or the people editing it.
Two more limits. This works in Confluence only, because the Jira apps store diagrams differently. And Claude can only create or change pages that you yourself are allowed to edit.
What admins control
Letting AI tools write into Confluence is a fair thing for an admin to question. Here is what Secure MCP for Confluence gives you:
- No vendor servers in between. The app does not send content outside Atlassian Confluence and Forge. Tokens are stored in the app's Forge storage. Content does reach the AI tool each user connects, so your existing policy for that tool applies.
- Each person's own permissions. Every call runs as the user who made it, never as a shared service account, so the assistant sees and changes only what that person could.
- Site-wide scope. Admins allow or exclude spaces, add a CQL filter, and switch off tool groups such as page creation or comments. Changes apply to every user immediately.
- Read-only by choice. Users pick read-only or read & write when they create a token.
- Tokens expire after at most 90 days. 10 active tokens per person. Admins can revoke every active token at once.
- Audit log. Every tool call is recorded with time, user, tool, target and whether it was allowed or denied. Entries can be exported to CSV.
Mermaid Diagrams Macro for Confluence carries the Runs on Atlassian badge, so it does not send data outside Atlassian either.
If you run a pilot, I’d like to hear how it goes and where it falls short. Which diagram has your team been putting off drawing? Tell me in the comments.
Disclosure: I work at Apportunity, the company that makes both apps in this article.
