Task	Tool	Notes
Read pages	MCP tools	`confluence_get_page`, `confluence_search`
Small text-only uploads (<10KB)	MCP tools	`confluence_create_page`, `confluence_update_page`
Large documents (>10KB)	`upload_confluence_v2.py`	REST API, no size limits
Documents with images	`upload_confluence_v2.py`	Handles attachments automatically
Git-to-Confluence sync	mark CLI	Best for CI/CD workflows
Download pages to Markdown	`download_confluence.py`	Converts macros, downloads attachments

MCP Size Limits

MCP tools have size limits (10-20KB) for uploads. For large documents or pages with images, use the REST API via upload_confluence_v2.py:

# Upload large document
python3 ~/.claude/skills/confluence/scripts/upload_confluence_v2.py \
    document.md --id 780369923

# Dry-run preview
python3 ~/.claude/skills/confluence/scripts/upload_confluence_v2.py \
    document.md --id 780369923 --dry-run

MCP works for reading pages but not for uploading large content.

Prerequisites

Required

Atlassian MCP Server (mcp__atlassian-evinova) with Confluence credentials

Optional

mark CLI: Git-to-Confluence sync (brew install kovetskiy/mark/mark)
Mermaid CLI: Diagram rendering (npm install -g @mermaid-js/mermaid-cli)

Core Workflows

Download Pages to Markdown

# Single page
python3 ~/.claude/skills/confluence/scripts/download_confluence.py 123456789

# With child pages
python3 ~/.claude/skills/confluence/scripts/download_confluence.py --download-children 123456789

# Custom output directory
python3 ~/.claude/skills/confluence/scripts/download_confluence.py --output-dir ./docs 123456789

See Downloading Guide for details.

Upload Pages with Images

Convert diagrams to images first using design-doc-mermaid or plantuml skills
Reference images with standard markdown: ![Description](./images/diagram.png)
Upload via REST API:

python3 ~/.claude/skills/confluence/scripts/upload_confluence_v2.py \
    document.md --id PAGE_ID

See Image Handling Best Practices for details.

Search Confluence

mcp__atlassian-evinova__confluence_search({
  query: 'space = "DEV" AND text ~ "API"',
  limit: 10
})

Create/Update Pages (Small Documents)

// Create page
mcp__atlassian-evinova__confluence_create_page({
  space_key: "DEV",
  title: "API Documentation",
  content: "h1. Overview\n\nContent here...",
  content_format: "wiki"
})

// Update page
mcp__atlassian-evinova__confluence_update_page({
  page_id: "123456789",
  title: "Updated Title",
  content: "h1. New Content",
  version_comment: "Updated via Claude Code"
})

Sync from Git (mark CLI)

Add metadata to Markdown files:

<!-- Space: DEV -->
<!-- Parent: Documentation -->
<!-- Title: API Guide -->

# API Guide
Content...

Sync to Confluence:

mark -f documentation.md
mark --dry-run -f documentation.md  # Preview first

See mark Tool Guide for details.

Convert Between Formats

See Conversion Guide for the complete conversion matrix.

Quick reference:

Markdown	Wiki Markup
`# Heading`	`h1. Heading`
`bold`	`bold`
`italic`	`_italic_`
`code`	`{{code}}`
`[text](url)`	`[text\|url]`

Reference Documentation

Detailed guides in the references/ directory:

Guide	Purpose
Wiki Markup Reference	Complete syntax for Confluence Wiki Markup
Conversion Guide	Markdown to Wiki Markup conversion rules
Storage Format	Confluence XML storage format details
Image Handling	Workflows for images, Mermaid, PlantUML
mark Tool Guide	Git-to-Confluence sync with mark CLI
Troubleshooting	Common errors and solutions

Available MCP Tools

Tool	Description
`confluence_search`	Search using CQL or text
`confluence_get_page`	Retrieve page by ID or title
`confluence_create_page`	Create new page
`confluence_update_page`	Update existing page
`confluence_delete_page`	Delete page
`confluence_get_page_children`	Get child pages
`confluence_add_label`	Add label to page
`confluence_get_labels`	Get page labels
`confluence_add_comment`	Add comment to page
`confluence_get_comments`	Get page comments

Utility Scripts

Script	Purpose
`scripts/upload_confluence_v2.py`	Upload large documents with images
`scripts/download_confluence.py`	Download pages to Markdown
`scripts/convert_markdown_to_wiki.py`	Convert Markdown to Wiki Markup
`scripts/convert_wiki_to_markdown.py`	Convert Wiki Markup to Markdown
`scripts/render_mermaid.py`	Render Mermaid diagrams

Version: 2.1.0 | Last Updated: 2025-01-21

SpillwaveSolutions-confluence

Confluence Management Skill

Table of Contents

Quick Decision Matrix