mcp-markdown-to-confluence

An MCP (Model Context Protocol) server that converts Markdown files to Atlassian Document Format (ADF) and publishes them to Confluence. Mermaid diagrams are rendered to PNG images and uploaded as page attachments.

Features

• Convert Markdown → Confluence ADF with full formatting support (tables, code blocks, callouts, TOC)

• Render Mermaid diagrams to PNG via headless Chromium and attach them to pages

• Preview content before publishing

• Create new pages or update existing ones

• Publish from inline Markdown or directly from a .md file using frontmatter

Related MCP server: MCP Confluence Server

Installation

npm

npm install @neverprepared/mcp-markdown-to-confluence

From source

git clone https://github.com/neverprepared/mcp-markdown-to-confluence.git
cd mcp-markdown-to-confluence
npm install
npm run build

Configuration

Set the following environment variables:

Claude Code Setup

Add to your Claude Code MCP config (.claude/.claude.json):

{
  "mcpServers": {
    "markdown-to-confluence": {
      "command": "node",
      "args": ["/path/to/mcp-markdown-to-confluence/dist/index.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://your-org.atlassian.net",
        "CONFLUENCE_USERNAME": "you@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Tools

markdown_preview

Convert Markdown to ADF and return a text preview — no Confluence calls made.

markdown_publish

Publish Markdown to a Confluence page. By default shows a preview first.

markdown_publish_file

Read a .md file from disk and publish it. Page metadata is read from frontmatter.

Supported frontmatter keys:

---
connie-title: My Page Title
connie-space-key: ENG
connie-page-id: "123456"   # omit to create a new page
title: Fallback title      # used if connie-title is absent
---

Preview Flow

By default, markdown_publish and markdown_publish_file return a rendered preview and prompt you to confirm before publishing. To publish in one step, pass skip_preview: true.

# Step 1 — review
markdown_publish(markdown: "...", title: "My Page", spaceKey: "ENG")
→ returns preview text

# Step 2 — publish
markdown_publish(markdown: "...", title: "My Page", spaceKey: "ENG", skip_preview: true)
→ returns page URL

Mermaid Diagrams

Mermaid code blocks are automatically detected, rendered to PNG via headless Chromium (bundled with Puppeteer), and uploaded as Confluence page attachments. The first run will download Chromium (~170 MB).

```mermaid
flowchart TD
  A[Write Markdown] --> B[Preview]
  B --> C{Looks good?}
  C -- Yes --> D[Publish]
  C -- No --> A
```

License

MIT