md2confluence-mcp

Markdown to Confluence converter — MCP server that uploads Markdown files to Atlassian Confluence with auto-converted Mermaid diagrams, code blocks, and images.

Demo

Uploading showcase.md to Confluence with images and Mermaid diagrams

Features

• ✅ Mermaid diagrams → PNG (auto-converted via kroki.io)
• ✅ Code blocks → Confluence Code macro
• ✅ Images → Attachments (auto-uploaded)
• ✅ Tables, links, formatting → Preserved

Installation

Claude Code

Add to your Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "md2confluence-mcp"],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_EMAIL": "your@email.com",
        "CONFLUENCE_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Project-specific

Add to your project's .mcp.json:

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "md2confluence-mcp"],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_EMAIL": "your@email.com",
        "CONFLUENCE_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Get API Token

1. Go to https://id.atlassian.com/manage/api-tokens
2. Click "Create API token"
3. Copy the token to CONFLUENCE_TOKEN

Usage

Once configured, Claude Code can use these tools automatically.

Prompt Examples

Upload to your personal space

"Upload README.md to my personal Confluence space"

"Upload this document to my Confluence space"

Upload to a specific space (with URL)

"Upload docs/SETUP.md to Confluence here: https://company.atlassian.net/wiki/spaces/TEAM/overview"

"Create a new page in https://company.atlassian.net/wiki/spaces/~712020170fdaa4716743419285f156aa587665/overview with this content"

Update an existing page

"Update this Confluence page with the latest content: https://company.atlassian.net/wiki/spaces/TEAM/pages/123456/My+Page"

"Sync docs/API.md to https://company.atlassian.net/wiki/spaces/EN/pages/789012/API+Reference"

Create a child page (sub-page)

"Create a new page under https://company.atlassian.net/wiki/spaces/TEAM/pages/123456/Parent+Page"

"Add a sub-page to this page: https://company.atlassian.net/wiki/spaces/EN/pages/789012/Guide"

List and search

"Show me available Confluence spaces"

"Find Confluence pages about authentication in the EN space"

Space Key Format

Tip: You can extract the space key from a Confluence URL:

https://company.atlassian.net/wiki/spaces/TEAM/overview
                                        ^^^^ space key

https://company.atlassian.net/wiki/spaces/~712020.../overview
                                        ^^^^^^^^^^ personal space key

Tools

How It Works

flowchart LR
    A["Markdown"] --> B["Parse"]
    B --> C["Mermaid → kroki.io → PNG"]
    C --> D["Convert to Confluence HTML"]
    D --> E["Upload via REST API"]
    E --> F["Attach images"]

1. Parse - Extract content, remove front matter
2. Render - Convert Mermaid diagrams to PNG via kroki.io
3. Convert - Transform Markdown to Confluence storage format
4. Upload - Create/update page via Confluence REST API
5. Attach - Upload images as page attachments

Environment Variables

Development

# Clone
git clone https://github.com/Gyeom/md2confluence-mcp.git
cd md2confluence-mcp

# Install dependencies
npm install

# Build
npm run build

# Test locally
CONFLUENCE_URL=... CONFLUENCE_EMAIL=... CONFLUENCE_TOKEN=... npm start

License

MIT

Credits

• kroki.io - Diagram rendering API
• Model Context Protocol - MCP SDK
• Confluence REST API