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

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:

| Variable | Description | |---|---| | CONFLUENCE_BASE_URL | Your Confluence base URL, e.g. https://your-org.atlassian.net | | CONFLUENCE_USERNAME | Your Atlassian account email | | CONFLUENCE_API_TOKEN | Your Atlassian API token (create one here) |

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": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Tools

markdown_preview

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

| Parameter | Type | Required | Description | |---|---|---|---| | markdown | string | yes | Markdown content to preview | | title | string | yes | Page title |

markdown_publish

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

| Parameter | Type | Required | Description | |---|---|---|---| | markdown | string | yes | Markdown content | | title | string | yes | Confluence page title | | spaceKey | string | yes | Confluence space key (e.g. ENG) | | pageId | string | no | Existing page ID to update; omit to create a new page | | parentId | string | no | Parent page ID for new pages | | skip_preview | boolean | no | Set true to publish without preview (default: false) |

markdown_publish_file

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

| Parameter | Type | Required | Description | |---|---|---|---| | filePath | string | yes | Absolute path to the Markdown file | | skip_preview | boolean | no | Set true to publish without preview (default: false) |

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