confluence-mcp

Fast, surgical Confluence MCP server for AI agents.

What makes this different

Unlike generic Atlassian MCP servers, this one is Confluence-only and optimized for how AI agents actually work with documentation:

• Surgical section edits — Update a single section by heading name without touching the rest of the page
• Fast page tree download — Get an entire page hierarchy in one call
• Smart image handling — Upload images as attachments and auto-embed them in pages
• Markdown in/out — Read and write in markdown; storage format conversion is automatic
• Find & replace — Simple text replacement preserving all HTML structure
• Section-aware reading — Fetch just the section you need, not the whole page

Installation

Via uvx (recommended for MCP clients)

uvx --from git+https://github.com/1vecera/confluence-mcp confluence-mcp

Via pip

pip install git+https://github.com/1vecera/confluence-mcp

Configuration

Set these environment variables:

CONFLUENCE_URL=https://yoursite.atlassian.net
CONFLUENCE_USERNAME=you@company.com
CONFLUENCE_API_TOKEN=your-api-token

Get your API token at: https://id.atlassian.com/manage-profile/security/api-tokens

Claude Code config

Add to ~/.claude.json:

{
  "mcpServers": {
    "confluence": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/1vecera/confluence-mcp", "confluence-mcp"],
      "env": {
        "CONFLUENCE_URL": "https://yoursite.atlassian.net",
        "CONFLUENCE_USERNAME": "you@company.com",
        "CONFLUENCE_API_TOKEN": "your-token"
      }
    }
  }
}

Tools

Reading

Tool	Description
get_page	Get page content in markdown or storage format
get_page_tree	Download entire page hierarchy at once
get_page_sections	List all sections with their content
get_section	Get a specific section by heading name
search_pages	Search via CQL or simple text
list_page_images	List all image references in a page

Writing (surgical)

Tool	Description
update_page	Update entire page content
update_section	Replace only a specific section — the key surgical edit tool
append_to_section	Add content to end of a section
find_replace_in_page	Find and replace text preserving HTML
create_page	Create a new page

Attachments & Images

Tool	Description
list_attachments	List all attachments on a page
download_attachment	Download an attachment by filename
upload_attachment	Upload a file attachment
upload_image_and_embed	Upload image + optionally rewrite page to embed it

Labels

Tool	Description
get_labels	Get labels on a page
add_label	Add a label to a page

Examples

Surgical section update

Instead of downloading and re-uploading an entire page:

update_section(page_id="123456", heading="Status", new_content="Project is **on track** for Q2 delivery.")

Download entire doc tree

get_page_tree(page_id="123456", include_body=True)

Upload and embed an image

upload_image_and_embed(page_id="123456", filename="arch.png", image_base64="...", replace_url="https://old-host.com/arch.png")

Development

uv sync --extra dev
uv run pytest --cov=confluence_mcp --cov-report=term-missing

License

MIT