Confluence MCP Server

A lightweight MCP server that gives Claude (or any MCP-compatible client) direct, structured access to Confluence Cloud — search and read existing pages, map out space/folder hierarchies, and publish or update documentation without leaving the agent session.

Built out of a real need: turning scattered local runbooks, migration notes, and postmortems into properly organized, de-duplicated Confluence pages, automatically.

Why this exists

Confluence's web editor is fine for humans. It's not built for an agent that needs to: look up whether something's already documented, understand how a space is organized before adding to it, and publish clean Markdown without hand-converting it to Confluence's storage format every time. This server closes that gap with six small, composable tools.

Features

• Six tools, each doing one thing: list_spaces, search_pages, get_page, list_children, create_page, update_page
• Markdown in, Confluence storage format out — write normal Markdown (tables, fenced code blocks, lists), the server converts it
• Folder-aware — Confluence Cloud's native Folder content type is a common blind spot; this server surfaces it everywhere pages are surfaced
• Credentials never touch a config file — the API token is read from the macOS Keychain at process start, not stored in ~/.claude.json or any shell profile
• A CLAUDE.md house-style guide included — teaches any Claude session using this repo how to explore before writing, which document structure to follow, how to handle conflicting sources, and formatting gotchas that are easy to get wrong (like titles being plain text, not HTML)

Requirements

• Python 3.10+
• A Confluence Cloud account with API access
• macOS (Keychain-based credential storage is macOS-only — see Other operating systems below for the alternative)

Setup

1. Install dependencies

git clone https://github.com/Hamza-XP/confluence-mcp-server.git
cd confluence-mcp-server
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

2. Get your own Confluence API token

Don't reuse anyone else's token — generate your own at id.atlassian.com/manage-profile/security/api-tokens → Create API token.

3. Store the token in your Keychain

Run this yourself — it reads the token with hidden input, so it never appears in your shell history or gets seen by anything else:

read -s "?Confluence API token: " CFTOKEN && \
  security add-generic-password -a "$USER" -s confluence-mcp-token -w "$CFTOKEN" -U && \
  unset CFTOKEN && echo "stored"

4. Register the server with Claude Code

claude mcp add -s user confluence \
  -e CONFLUENCE_BASE_URL='https://YOURDOMAIN.atlassian.net/wiki' \
  -e CONFLUENCE_EMAIL='you@yourdomain.com' \
  -- /absolute/path/to/confluence-mcp-server/.venv/bin/python /absolute/path/to/confluence-mcp-server/server.py

-s user registers it for every Claude Code session on your machine, not just one project. Only the two values above go in the config — the token stays in Keychain, fetched fresh by the server each time it starts.

5. Restart Claude Code

MCP servers are spawned once per session, so open a new terminal and start a new claude session before the tools appear. Confirm with:

claude mcp get confluence

You should see Status: ✔ Connected.

Usage

Once connected, just ask Claude to work with Confluence naturally — "check if we already have docs on X," "find the infra folder for project Y and add a page," "update the runbook page with this new step." Claude will use search_pages and list_children to orient itself before writing, per the house style in CLAUDE.md.

Tool	Purpose
list_spaces	List all Confluence spaces visible to your account
search_pages	Full-text search, optionally scoped to a space
get_page	Fetch a page/folder's metadata and (optionally) body
list_children	List a page or folder's direct children — pages and folders
create_page	Publish a new page from Markdown
update_page	Update an existing page's title/body from Markdown

Security notes

• The API token lives only in the macOS Keychain (security service name confluence-mcp-token), never in a file this repo, your shell config, or Claude's own config touches.
• CONFLUENCE_BASE_URL and CONFLUENCE_EMAIL are not secrets and are stored as literal values in Claude Code's own config (~/.claude.json, permissions 600).
• Each teammate generates and stores their own token — tokens are personal and auditable per Atlassian account; never share one.

Other operating systems

security (Keychain) is macOS-only. On Linux or Windows, skip step 3 and pass the token directly when registering instead:

-e CONFLUENCE_TOKEN='your-token-here'

This is weaker (the token sits in plaintext in ~/.claude.json) — if that matters for your setup, adapt _load_token() in server.py to use your OS's native credential store (libsecret/secret-tool on Linux, Credential Manager via keyring on Windows) instead. Contributions welcome.

How it works

The server talks to Confluence's REST API v1 (/rest/api/...) over HTTPS using your email

• API token as HTTP Basic Auth. It's built on the official mcp Python SDK and runs as a stdio subprocess — no network port, no daemon, nothing running when Claude Code isn't.

License

MIT