Skip to main content
Glama

md2confluence-mcp

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

npm License: MIT

Demo

demo

Uploading showcase.md to Confluence with images and Mermaid diagrams

Related MCP server: Confluence MCP Server

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"
"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

Available Tools

6 tools
create_child_pageA

Create a NEW page as a child (sub-page) of an existing page.

⚠️ MUST USE THIS TOOL WHEN:

  • User wants to create a page "under", "below", "하위에", or "beneath" another page

  • User provides a parent page URL and wants NEW content added as a sub-page

  • User says "put this under [page]", "[page] 하위에 넣어줘", "add as child of [page]"

❌ WARNING: upload_page with a page URL will UPDATE that page, NOT create a child. ✅ ALWAYS use create_child_page for hierarchical page creation.

Inputs: content (required), title (required), parentPageUrl (required).

list_spacesA

List available Confluence spaces. NOTE: Do NOT use this before upload_page. Only use when user explicitly asks to browse/list spaces. For uploads, ask user directly for space key or URL.

Inputs: limit, type.

search_pagesC

Search for Confluence pages

Inputs: query (required), spaceKey, limit.

sync_fileA

Sync a LOCAL file to a Confluence page. This tool reads the file directly from the filesystem.

⚠️ CRITICAL INSTRUCTIONS FOR AI:

  • file_path MUST be the EXACT path specified by the user

  • Do NOT infer or guess file path based on Confluence page title or URL content

  • If user says "sync readme.md to URL", find "readme.md" file, NOT files matching page title

  • If multiple files match, ask user to specify the exact path

  • This tool handles file reading internally - just pass the path

Examples:

  • User: "sync readme.md to https://..." → file_path: "/path/to/readme.md" (find readme.md)

  • User: "sync /docs/guide.md to https://..." → file_path: "/docs/guide.md" (exact path)

Inputs: file_path (required), page_url (required), title.

update_pageC

Update an existing Confluence page with Markdown content

Inputs: content (required), pageId (required), title.

upload_pageA

Upload Markdown to Confluence at SPACE ROOT level or UPDATE existing page.

⚠️ ROUTING RULES:

  • Page URL provided → UPDATES that existing page (ignores parentId)

  • Space key/URL only → Creates NEW page at space root level

❌ DO NOT use this tool to create child/sub-pages. ✅ Use 'create_child_page' tool instead for hierarchical pages.

Mermaid diagrams are auto-converted to images.

Inputs: content (required), title (required), space (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation4/5

    The tools are mostly distinct with clear purposes, but there is some potential confusion between 'upload_page' and 'create_child_page' for page creation scenarios, as both involve creating pages but under different conditions. The descriptions provide explicit routing rules to mitigate this, but an agent might still need to carefully parse user intent to choose correctly.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear verb_noun structures (e.g., create_child_page, list_spaces, search_pages, sync_file, update_page, upload_page). This consistency makes the tool set predictable and easy to understand at a glance.

    Tool Count5/5

    With 6 tools, the server is well-scoped for its purpose of managing Confluence pages from Markdown files. The count is appropriate, covering key operations like listing, searching, creating, updating, and syncing without being overwhelming or too sparse.

    Completeness4/5

    The tool set covers essential CRUD-like operations for Confluence pages (create, update, sync, list, search), but there are minor gaps such as the lack of a delete_page tool for full lifecycle management. However, agents can likely work around this by using other methods or the existing tools for most workflows.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers