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

Related MCP server: confluence-mcp-server

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

Writing (surgical)

Attachments & Images

Labels

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