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