Enables programmatic interaction with Atlassian Confluence to manage spaces and pages, allowing for automated documentation workflows and content synchronization.
Converts and uploads Markdown documents to Confluence, with support for Mermaid diagrams, code macros, image attachments, and hierarchical page management.
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
Click "Create API token"
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 |
|
Personal space |
|
|
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 keyTools
Tool | Description |
| Create a new Confluence page from Markdown |
| Update an existing page |
| Create a new page under an existing page |
| Sync a local file to an existing page |
| List available spaces |
| 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"]Parse - Extract content, remove front matter
Render - Convert Mermaid diagrams to PNG via kroki.io
Convert - Transform Markdown to Confluence storage format
Upload - Create/update page via Confluence REST API
Attach - Upload images as page attachments
Environment Variables
Variable | Required | Description |
| ✅ | e.g., |
| ✅ | Your Atlassian account email |
| ✅ | 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 startLicense
MIT
Credits
kroki.io - Diagram rendering API
Model Context Protocol - MCP SDK