confluence-mcp

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