md2confluence-mcp

MCP server for uploading Markdown to Confluence with 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": "[email protected]",
        "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": "[email protected]",
        "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

| Type | Format | Example | |------|--------|---------| | Global space | Short key | TEAM, EN, PROD | | Personal space | ~ + ID | ~712020170fdaa4716743419285f156aa587665 |

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

| Tool | Description | |------|-------------| | upload_page | Create a new Confluence page from Markdown | | update_page | Update an existing page | | create_child_page | Create a new page under an existing page | | sync_file | Sync a local file to an existing page | | list_spaces | List available spaces | | search_pages | Search for pages |

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

| Variable | Required | Description | |----------|----------|-------------| | CONFLUENCE_URL | ✅ | e.g., https://your-domain.atlassian.net/wiki | | CONFLUENCE_EMAIL | ✅ | Your Atlassian account email | | CONFLUENCE_TOKEN | ✅ | API token |

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