www-confluence-mcp 1.0.0

MCP server providing Confluence Server/Data Center integration: page management, search, spaces, and more.

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.

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

System Requirements

Requirement	Version
uv	Install guide
Python	3.10+ (managed automatically by uv)
Confluence	Server 5.6+ / Data Center 6.0+

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: Run directly with uvx (recommended)

No clone needed. Runs from PyPI. Updates automatically on each run:

uvx www-confluence-mcp

MCP client config:

{
  "mcpServers": {
    "www-confluence-mcp": {
      "command": "uvx",
      "args": ["www-confluence-mcp"],
      "env": {
        "CONFLUENCE_URL": "https://confluence.example.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your-pat-here"
      }
    }
  }
}

Option 2: Install as a uv tool

# From PyPI
uv tool install www-confluence-mcp

# After installation, the command is available globally:
www-confluence-mcp

To update or reinstall:

uv tool upgrade www-confluence-mcp
# or force reinstall latest:
uv tool install --force www-confluence-mcp@latest

Option 3: Run from local source (for development)

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

To update:

git pull && uv sync

MCP client config (local source):

{
  "mcpServers": {
    "www-confluence-mcp": {
      "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"
      }
    }
  }
}

Option 4: Install from built wheel

cd /path/to/www-confluence-mcp
uv build
uv tool install dist/*.whl

Authentication

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

Method	Environment Variables
Personal Access Token (PAT) (recommended)	CONFLUENCE_PERSONAL_TOKEN
Basic Auth (username + password)	CONFLUENCE_USERNAME + CONFLUENCE_PASSWORD

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

Environment Variables

Variable	Description	Default
CONFLUENCE_URL	Confluence Server/DC base URL (required)	—
CONFLUENCE_PERSONAL_TOKEN	Personal Access Token for PAT auth	—
CONFLUENCE_USERNAME	Username for Basic auth	—
CONFLUENCE_PASSWORD	Password for Basic auth	—
CONFLUENCE_SSL_VERIFY	Verify SSL certificates	true
CONFLUENCE_TIMEOUT	HTTP request timeout in seconds	30
CONFLUENCE_MAX_RESULTS	Default max results per query (1..100)	25
CONFLUENCE_READ_ONLY	Disable write tools (true/false)	true
CONFLUENCE_SPACES_FILTER	Comma-separated space keys to filter searches	—
CONFLUENCE_HTTP_PROXY	HTTP proxy URL	—
CONFLUENCE_HTTPS_PROXY	HTTPS proxy URL	—
CONFLUENCE_DEBUG	Enable debug logging (1/true/yes/on)	false

Provided Tools

Read Tools (15)

• confluence_search — Search content by text or CQL query
• confluence_get_page — Get page by ID, title+space_key, or URL
• confluence_get_page_children — Get child pages
• confluence_get_page_ancestors — Get ancestor pages (breadcrumb)
• confluence_get_spaces — List spaces
• confluence_get_space — Get space by key
• confluence_get_pages_in_space — List pages in a space
• confluence_get_comments — Get page comments
• confluence_get_labels — Get page labels
• confluence_get_attachments — List page attachments
• confluence_download_attachment — Download a single attachment
• confluence_download_content_attachments — Download all attachments
• confluence_get_page_history — Get page version history
• confluence_get_space_page_tree — Get space page hierarchy
• confluence_get_page_images — Get page images as base64
• confluence_search_user — Search for users

Write Tools (10) — only when CONFLUENCE_READ_ONLY=false

• confluence_create_page — Create a new page
• confluence_update_page — Update an existing page
• confluence_delete_page — Delete a page
• confluence_move_page — Move page to another space/parent
• confluence_add_comment — Add a comment
• confluence_reply_to_comment — Reply to a comment
• confluence_add_labels — Add labels to a page
• confluence_delete_label — Remove a label
• confluence_upload_attachment — Upload a file
• confluence_upload_attachments — Upload multiple files
• confluence_delete_attachment — Delete an attachment

Quick Verification

# Search Confluence
CONFLUENCE_URL=https://confluence.example.com CONFLUENCE_PERSONAL_TOKEN=your-token \
uv run python -c "
import asyncio
from www_confluence_mcp.server import mcp
asyncio.run(mcp.run(transport='stdio'))
"

# Or just run the server
CONFLUENCE_URL=https://confluence.example.com CONFLUENCE_PERSONAL_TOKEN=your-token \
uv run www-confluence-mcp

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.

License

MIT