Better Confluence MCP

MCP server for Confluence with local filesystem caching - designed specifically for coding agents like Claude Code, Cursor, Windsurf, and similar AI assistants.

Why This Approach?

Coding agents work best with files. They excel at reading, editing, and managing files on your filesystem. This MCP leverages that strength:

1. Sync Confluence spaces to local .html files

2. Edit files directly using the agent's native file tools

3. Push changes back to Confluence

No complex API calls mid-conversation. No context window bloat from fetching pages repeatedly. Just simple file operations that agents already do well.

Related MCP server: MCP Confluence Server

How It Works

Confluence Space                    Local Filesystem
    ├── Page A          sync_space      .better-confluence-mcp/
    │   ├── Page B      ─────────►          └── SPACE_KEY/
    │   └── Page C                              ├── page_id_A/
    └── Page D                                  │   ├── Page A.html
                                                │   ├── page_id_B/
                        push_page_update        │   │   └── Page B.html
                        ◄───────────────        │   └── page_id_C/
                                                │       └── Page C.html
                                                └── page_id_D/
                                                    └── Page D.html

The folder structure mirrors the Confluence page hierarchy. Each page is stored as an HTML file named after the page title.

Features

• Fast & token-efficient editing - Agents make surgical edits to local files instead of regenerating entire pages, saving tokens

• Large page support - Edit pages of any size without context window limits

• Mermaid diagrams - Render mermaid diagrams to PNG and embed them in pages

• Tree-based storage - Folder structure matches Confluence hierarchy

• Incremental sync - Only fetches pages modified since last sync (using CQL)

• Version conflict detection - Prevents overwriting external edits

• Two transport modes - stdio for local agents, streamable HTTP for remote/shared deployments

Transport Modes

The server supports two transport modes:

stdio Mode (Default)

The standard mode for local AI assistants. Authentication is configured via environment variables and all tools are available.

better-confluence-mcp

Streamable HTTP Mode (Read-Only)

Runs as a read-only HTTP server for remote access. Designed for shared deployments where multiple users connect to the same server. All write operations are disabled - no creating, updating, or uploading pages.

better-confluence-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Key differences from stdio mode:

• Auth via HTTP headers - credentials are sent per-request, not stored in env vars

• Read-only - all write tools are disabled (no create, update, upload)

• Search tool - confluence_confluence_search is enabled (only available in HTTP mode)

• Per-user isolation - each user's synced data is stored in a separate directory

Available Tools

stdio Mode

HTTP Mode (Read-Only + Search)

In HTTP mode, read_page includes the full HTML content in the JSON response (since the client can't access local files on the server).

Search Tool (HTTP Mode)

The confluence_confluence_search tool provides local full-text search through synced Confluence pages. It syncs the space before every search to ensure content is up to date.

Features

• Title + body search - matches in page titles are ranked higher

• Relevance ranking - title match (100) > heading match (10) > body match (1)

• Regex support - set is_regex: true to use regex patterns

• Context lines - shows surrounding lines around each match (like grep -C)

• Multi-space - search across multiple spaces in one call

Parameters

Examples

Plain text search:

{"space_keys": "IT", "query": "kubernetes"}

Regex search for IP addresses:

{"space_keys": "IT,DEV", "query": "\\b\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\b", "is_regex": true}

Case-sensitive search with more context:

{"space_keys": "IT", "query": "PostgreSQL", "case_sensitive": true, "context_lines": 5}

Response

Results are sorted by relevance score:

{
  "success": true,
  "space_keys": ["IT"],
  "pages_searched": 251,
  "pages_matched": 4,
  "results": [
    {
      "page_id": "1506803713",
      "title": "NetBird dokumentace",
      "space_key": "IT",
      "url": "https://...",
      "relevance_score": 105,
      "title_matched": true,
      "match_count": 3,
      "matches": [
        {
          "line": 4,
          "match_text": "Netbird.io VPN allows access to...",
          "location": "body",
          "context": [
            {"line": 3, "text": "...", "is_match": false},
            {"line": 4, "text": "Netbird.io VPN allows...", "is_match": true},
            {"line": 5, "text": "...", "is_match": false}
          ]
        }
      ]
    }
  ]
}

Quick Start

stdio Mode (Local Agent)

Add to Claude Code (~/.claude.json) or Cursor (Settings → MCP):

{
  "mcpServers": {
    "confluence": {
      "command": "uvx",
      "args": ["better-confluence-mcp"],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
      }
    }
  }
}

HTTP Mode (Docker)

docker run -p 8000:8000 \
  -e CONFLUENCE_URL=https://your-company.atlassian.net/wiki \
  twinity1/better-confluence-mcp

Or build from source:

docker build -t better-confluence-mcp .

The only required environment variable is CONFLUENCE_URL. User credentials are provided per-request via HTTP headers.

Authentication Headers

Two formats are supported:

Basic Auth:

Authorization: Basic base64(username:api_token)

Custom headers:

X-Confluence-Username: your.email@company.com
X-Confluence-Token: your_api_token

Requests without valid authentication receive a 401 response.

Per-User Isolation (HTTP Mode)

In HTTP mode, each user's synced data is stored in a separate directory namespaced by their username. This ensures:

• User A cannot see pages synced by User B

• Confluence API calls use the requesting user's credentials, so access controls are enforced

• If a user doesn't have access to a space, the sync fails with a 403 from Confluence

.better-confluence-mcp/
└── _users/
    ├── a1b2c3d4_alice/
    │   └── IT/
    │       ├── _metadata.json
    │       └── ...
    └── e5f6a7b8_bob/
        └── DEV/
            └── ...

In stdio mode, storage uses the shared root directory (no user namespace) since there's only one user.

Usage Examples

Sync a space

"Sync the DEV space from Confluence"

The agent calls confluence_sync_space with space_key: "DEV". Pages are saved to .better-confluence-mcp/DEV/.

Edit a page

"Update the Getting Started guide in our docs"

The agent:

1. Reads the HTML file from .better-confluence-mcp/...

2. Edits the content using its file editing tools

3. Calls confluence_push_page_update to push changes

Working with attachments

"Download all attachments from the Getting Started page"

The agent calls confluence_download_attachments with the page ID. Attachments are saved to .better-confluence-mcp/SPACE/page_id/attachments/.

"Upload this screenshot to the deployment docs"

The agent calls confluence_upload_attachment with the page ID and file path.

Version conflict handling

If someone else edited the page in Confluence:

{
  "error": "Page was modified externally",
  "message": "The page was edited in Confluence (version 5) since your last sync (version 4). The page has been re-synced. Please review the changes and try again.",
  "local_version": 4,
  "confluence_version": 5
}

The page is automatically re-synced with the latest content.

File Structure

.better-confluence-mcp/
└── SPACE_KEY/
    ├── _metadata.json          # Space metadata with page tree
    └── page_id/
        ├── Page Title.html     # Page content
        ├── attachments/        # Downloaded attachments (optional)
        │   ├── screenshot.png
        │   └── document.pdf
        └── child_page_id/
            └── Child Page.html

Each HTML file includes metadata in a comment header:

<!--
  Page ID: 123456
  Title: Getting Started
  Space: DEV
  Version: 3
  URL: https://your-company.atlassian.net/wiki/spaces/DEV/pages/123456
  Synced: 2025-01-15T10:30:00+00:00
-->
<h1>Getting Started</h1>
<p>Welcome to our documentation...</p>

Configuration Options

Environment Variables

CLI Options

Why "Better"?

This is a fork of mcp-atlassian optimized for coding agents:

Compatibility

Development

# Clone the repo
git clone https://github.com/twinity1/better-confluence-mcp
cd better-confluence-mcp

# Install dependencies
uv sync

# Run tests
uv run pytest tests/

# Run the server locally (stdio)
uv run better-confluence-mcp

# Run the server locally (HTTP)
uv run better-confluence-mcp --transport streamable-http --port 8000

License

MIT License - see LICENSE file.

Based on mcp-atlassian by sooperset.