Confluence Mcp Server

Confluence MCP Server

[](https://github.com/pankaj28843/confluence-mcp-server/actions/workflows/ci.yml)

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pankaj28843
• Source: pankaj28843/confluence-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.