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.

Parameter	Type	Default	Description
`query`	string	required	Natural language query (translated to CQL)
`limit`	int (1–25)	`5`	Maximum results to return
`spaces`	string[]	`null`	Filter by space keys (e.g. `["ENG", "OPS"]`)
`labels`	string[]	`null`	Filter by page labels
`titles_only`	bool	`false`	Search titles only (faster, lower recall)
`fuzzy`	bool	`true`	Parallel term-split search for better recall
`modified_after`	string	`"2y"`	Recency filter. Shorthands: `1d` `7d` `30d` `90d` `6M` `1y` `2y` `5y` or ISO date. Set to `null` for all time
`created_after`	string	`null`	Filter by creation date (same format)

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.

Parameter	Type	Description
`content_id`	string	Numeric content ID returned by `search_confluence`

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:

Variable	Default	Description
`CONFLUENCE_URL`	—	Base URL of your Confluence instance
`CONFLUENCE_PERSONAL_ACCESS_TOKEN`	—	Bearer token for authentication
`CONFLUENCE_VERIFY_TLS`	`true`	Enforce TLS certificate validation
`CONFLUENCE_REQUEST_TIMEOUT`	`20`	HTTP timeout in seconds
`CONFLUENCE_MAX_RETRIES`	`3`	Retry attempts for transient failures
`CONFLUENCE_CACHE_ENABLED`	`true`	Enable/disable disk cache
`CONFLUENCE_CACHE_DIR`	`.cache/confluence_mcp`	Cache directory path
`CONFLUENCE_CACHE_TTL_SEARCH`	`300`	Search cache TTL (seconds)
`CONFLUENCE_CACHE_TTL_CONTENT`	`900`	Page content cache TTL (seconds)

Transport variables (HTTP mode)

Variable	Default	Description
`CONFLUENCE_MCP_TRANSPORT`	`stdio`	`stdio`, `http`, `sse`, or `streamable-http`
`CONFLUENCE_MCP_HOST`	`0.0.0.0`	Bind address (HTTP mode)
`CONFLUENCE_MCP_PORT`	`43043`	Listen port (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