www-confluence-mcp

MCP (Model Context Protocol) server providing Confluence Server/Data Center integration — page management, search, spaces, comments, labels, attachments, and more.

Gives AI assistants (Qoder, Claude Desktop, Cursor, etc.) the ability to read and write Confluence content through a single MCP server with 25 tools (24 tools + 1 prompt tool) and 2 built-in prompts.

Note: This server targets Confluence Server/Data Center only (v1 REST API). Confluence Cloud is not supported.

System Requirements

Install uv

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS (Homebrew):

brew install uv

Installation

Option 1: From PyPI (recommended)

uvx — one-shot run, auto-updates on every launch:

uvx www-confluence-mcp

uv tool install — persistent global command:

# Install (or update to latest):
uv tool install --force www-confluence-mcp@latest

# Run:
www-confluence-mcp

# Update later:
uv tool install --force www-confluence-mcp@latest

Option 2: From source or wheel (development)

git clone https://github.com/naifs/www-confluence-mcp.git
cd www-confluence-mcp
uv sync

# Run directly:
uv run www-confluence-mcp

# Or build and install as a global command:
uv build
uv tool install --force dist/*.whl

# Update later:
git pull && uv sync
# or rebuild:
uv build && uv tool install --force dist/*.whl

MCP Client Config

All variants share the same env block. The only difference is command and args:

{
  "mcpServers": {
    "www-confluence-mcp": {

      // Option 1a: uvx — ephemeral run from PyPI, auto-updates on each launch
      "command": "uvx",
      "args": ["www-confluence-mcp"],

      // Option 1b: uv tool install — globally installed command, no args needed
      // "command": "www-confluence-mcp",
      // "args": [],

      // Option 2: local source — run from a cloned repo (replace path)
      // "command": "uv",
      // "args": ["run", "--project", "/absolute/path/to/www-confluence-mcp", "www-confluence-mcp"],

      "env": {
        "CONFLUENCE_URL": "https://confluence.example.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your-pat-here"
      }
    }
  }
}

How to use: uncomment exactly one of the command/args pairs above and delete the rest.

Authentication

The server supports two authentication methods for Confluence Server/Data Center:

PAT takes priority if both are configured. CONFLUENCE_API_TOKEN is accepted as a legacy fallback for CONFLUENCE_PASSWORD.

Environment Variables

Provided Tools

Read Tools (14)

• confluence_search — Search content by text or CQL query
• confluence_get_page_content — Get page by ID or URL (ALWAYS tries to save to {workspace}/tmp/page_{pageId}.md via save_path)
• confluence_list_ancestors — Get ancestor pages (breadcrumb)
• confluence_list_spaces — List all spaces or get one by key
• confluence_get_page_tree — Get pages from a space (tree) or children of a page
• confluence_list_comments — Get page comments
• confluence_list_labels — Get page labels
• confluence_list_attachments — List page attachments
• confluence_download_attachments — Download attachments to disk (all or by IDs, saves to {workspace}/tmp/)
• confluence_list_versions — Get page version history
• confluence_get_page_images — Get page images as base64
• confluence_get_user — Search for users by username, email, or display name
• confluence_validate_page — Validate Confluence page with XHTML validation and round-trip checking
• confluence_mcp_info — Get server configuration info (all environment variables, defaults, examples)
• confluence_mcp_status — Health check (server status, uptime, version, tool count, connection status)

Write Tools (10) — only when CONFLUENCE_READ_ONLY=false

• confluence_new_page — Create a new page
• confluence_update_page — Update an existing page
• confluence_delete_pages — Delete multiple pages in batch
• confluence_move_page — Move page to another space/parent
• confluence_add_comment — Add a comment to a page
• confluence_add_labels — Add labels to a page
• confluence_delete_labels — Delete multiple labels from multiple pages in batch
• confluence_upload_attachments — Upload one or more files as attachments
• confluence_delete_attachments — Delete multiple attachments in batch

Prompt Tool (1)

• confluence_mcp_prompts — List all loaded external prompt definitions, or get full prompt content by name

Built-in Prompts

The server includes 2 built-in prompts accessible via confluence_mcp_prompts:

• update_page_from_template — Merge source content with a template (supports IN-PLACE update or NEW PAGE creation)
• how_to_write_prompts — Guide for creating YAML prompt definitions

Prompts are loaded from the builtin prompts directory and can be extended with custom prompts via CONFLUENCE_PROMPTS_DIR.

Remote Deployment (HTTP Mode)

The server supports running as a remote HTTP service, allowing multiple users to connect with their own Confluence credentials.

Quick Start

# Start in HTTP mode
CONFLUENCE_MCP_TRANSPORT=http \
CONFLUENCE_URL=https://confluence.example.com \
uvx www-confluence-mcp

The server listens on 127.0.0.1:8080 by default. Set CONFLUENCE_MCP_HOST=0.0.0.0 to expose externally.

Client Configuration

Users connect by passing their credentials as HTTP headers — the same env var names used locally:

{
  "mcpServers": {
    "confluence": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "CONFLUENCE_URL": "https://confluence.example.com",
        "CONFLUENCE_PERSONAL_TOKEN": "user-pat-token"
      }
    }
  }
}

This works identically to local mode — the only difference is credentials go in headers instead of env vars.

How It Works

1. Local mode (stdio): Credentials come from environment variables → shared singleton HTTP client (unchanged behavior)
2. Remote mode (HTTP): Credentials come from request headers → per-user cached HTTP client (1-hour TTL)

Each user gets their own isolated Confluence session. Clients are cached to avoid recreating connections on every request.

Production Deployment

# Run with uvicorn (recommended for production)
CONFLUENCE_MCP_TRANSPORT=http \
CONFLUENCE_MCP_HOST=0.0.0.0 \
CONFLUENCE_MCP_PORT=8080 \
uv run www-confluence-mcp

Behind a reverse proxy (nginx):

server {
    listen 443 ssl;
    server_name mcp.example.com;

    location /mcp {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
}

Troubleshooting

uv not found

Install uv and reopen your terminal. See System Requirements.

Dependencies missing

uv sync

MCP tools not appearing in client

1. Check that the MCP client config JSON is valid.
2. Ensure the --project path is absolute and correct.
3. Reload the MCP client after config changes.
4. Check CONFLUENCE_DEBUG=true for detailed logs.

Authentication error

• Verify CONFLUENCE_URL points to your Server/DC instance (not *.atlassian.net).
• For PAT: ensure the token is valid and not expired.
• For Basic auth: ensure both CONFLUENCE_USERNAME and CONFLUENCE_API_TOKEN are set.

Wrong project path in config

The --project argument must point to the root directory of www-confluence-mcp (where pyproject.toml is located), not to the src/ subdirectory.

Rate limiting errors (429)

The server includes built-in client-side rate limiting to prevent hitting Confluence's limits. Defaults: 10 tokens/second, burst of 20. Tune with CONFLUENCE_RATE_LIMIT_TOKENS and CONFLUENCE_RATE_LIMIT_BURST.

License

MIT