MCP Server - Confluence Image upload/insert to docs

I've been struggling with this whole week... 😅
I mean, it's not that bad, but it can get quite annoying when you have to add/copy attachments manually.

Anyhow, as Viswanathan said, ECO-1265 is a place to look at > I'd recommend setting yourself as a watcher. I do believe they've mentioned somewhere that this should be shipped this or next quarter, but we'll see. 👀
It will definitelly save a lot of time in some cases.

Cheers,
Tobi

Hi Scott — the missing half probably isn't your config: Confluence Cloud REST v2 has no "create attachment" operation at all. /wiki/api/v2/pages/{id}/attachments is read-only, so an MCP server built purely on v2 can write the page text but has nowhere to put the file. Uploading still lives on the older v1 endpoint, which is why it tends to be absent from MCP tool sets.

While ECO-1265 is open you can close the loop yourself with two calls, and they wrap neatly into one custom MCP tool:

1) Upload the file (v1, multipart)

POST /wiki/rest/api/content/{pageId}/child/attachment

header: X-Atlassian-Token: nocheck

form fields: file=@diagram.svg and minorEdit=true

Scope: write:confluence-file on a classic-scope app, or the granular attachment-write scope. Worth checking first — a read-only token here tends to fail quietly rather than loudly.

2) Reference it from the page body (v2 update)

PUT /wiki/api/v2/pages/{id} with body.representation = "storage" and the markup

<ac:image><ri:attachment ri:filename="diagram.svg"/></ac:image>

That request also needs id, status, title and version.number = current + 1. Keeping the body in storage rather than ADF is what makes the image reference a one-liner.

Two things that cost me time: attach first and update the body second, otherwise the reference renders as a broken image; and if a model-generated SVG looks wrong on the page (they often carry foreignObject or system fonts), re-export it as PNG once to confirm you're looking at an SVG problem and not an API problem.

Disclosure: I work on Diagram.now, a Confluence diagramming app, so I'm biased on this last part. It may still be worth weighing the other shape of the problem: an attachment is a flat picture, so every "move that one box" means regenerating and re-uploading the whole file. Keeping it as an editable diagram on the page — importing the Mermaid your model already emits, or describing it in text and adjusting it in the editor afterwards — avoids that round trip. https://marketplace.atlassian.com/apps/523472243/diagram-now-diagram-editor-for-confluence?utm_source=atlassian-community&utm_content=mcp-image-insert

The two REST calls above are worth having either way.

Hi @Scott Melhop 

Welcome to the community !!

As Vishwa suggest a mktplace app can help to render mermaid diagrams directly in Confluence. If you are open to try out one, take a look at 

Mermaid Diagrams & Charts for Confluence

The app has more than 15 diagramming templates and also integrates with your code repositories like GitHub/Bitbucket.

Disclaimer : I am part of the app dev team

The v1-then-v2 split already in the thread is the real constraint: Cloud v2 can list attachments but cannot create them, so an MCP server built only on v2 will write the page body and leave the image as a broken reference.

What has been working:

1. POST the file to /wiki/rest/api/content/{pageId}/child/attachment with X-Atlassian-Token: nocheck and write:confluence-file (or the granular attachment-write scope). Attach first.
2. Then PUT /wiki/api/v2/pages/{id} with storage markup that references that filename, bumping version.number. Body-first will 404 the image.
3. For diagrams you will edit again, keep Mermaid (or another in-page diagram) in storage. A PNG attachment is a one-shot picture; every “move that box” means regenerate + re-upload.
4. If the model SVG looks empty on the page, it is often foreignObject / fonts. Re-export a PNG only to confirm that — don’t treat PNG as the long-term source of truth.

If that PNG later leaves Confluence (download, campaign pack, Instagram), the attachment store does not rewrite C2PA / XMP the generator wrote into the bytes. Keep the Confluence master, and check the exact still you will post. A Confluence-friendly pre-upload stills check is enough for that copy; it does not replace MCP, the v1 upload, or Atlassian’s own AI disclosure.