Confluence MCP Server

An MCP (Model Context Protocol) server that connects AI assistants to your Confluence instance. It exposes two tools — search and fetch — letting any MCP-compatible client (Claude Desktop, Cursor, Windsurf, etc.) query and read Confluence pages in real time.

Features

• 🔍 Fuzzy search — splits multi-word queries into parallel CQL searches and merges results by relevance

• 📄 Full page hydration — retrieves storage body, version info, labels, and ancestors as clean Markdown

• ⚡ Disk cache — search and content responses are cached locally to reduce API load

• 🔒 Read-only — all tools are annotated readOnlyHint: true; nothing is ever written to Confluence

• 🐳 Docker-ready — one-command deployment via deploy_confluence_mcp.py

Prerequisites

• Python 3.11+ and uv or Docker

• A Confluence instance accessible over HTTP(S)

• A Confluence Personal Access Token

Quickstart

1. Configure credentials

cp .env.example .env

Edit .env:

CONFLUENCE_URL=https://confluence.example.com
CONFLUENCE_PERSONAL_ACCESS_TOKEN=your_token_here

2a. Run with uv (stdio — for Claude Desktop / Cursor)

uv sync
uv run python -m confluence_search.fastmcp_app

2b. Run with Docker (HTTP)

python deploy_confluence_mcp.py          # builds image + starts container on :43043

Or manually:

docker build -t confluence-mcp-server .
docker run -d --name confluence-mcp-server \
  --env-file .env \
  -p 43043:43043 \
  confluence-mcp-server

Connecting an MCP client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "confluence": {
      "command": "uv",
      "args": ["run", "python", "-m", "confluence_search.fastmcp_app"],
      "cwd": "/path/to/confluence-mcp-server",
      "env": {
        "CONFLUENCE_URL": "https://confluence.example.com",
        "CONFLUENCE_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Cursor / Windsurf (HTTP transport)

Point your MCP client at http://127.0.0.1:43043/mcp after starting the Docker container.

MCP Tools

search_confluence

Execute a CQL search against Confluence.

Returns a ranked list of matching pages with title, URL, space, excerpt, and matched labels.

fetch_confluence_page

Hydrate a single page by its Confluence content ID.

Returns the page as a Markdown document including metadata header (URL, space, version, last-modified date, labels, ancestor breadcrumb) followed by the full page body.

Configuration reference

All settings are read from environment variables or .env:

Transport variables (HTTP mode)

Development

uv sync
uv run pytest -m unit --cov=confluence_search/ --cov-report=term-missing
uv run ruff check confluence_search/ tests/
uv run ruff format confluence_search/ tests/

The test suite requires 100% coverage — enforced in CI.

License

MIT