# Confluence MCP Server

A lightweight [MCP](https://modelcontextprotocol.io) 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`](./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](#other-operating-systems) below for the alternative)

## Setup

### 1. Install dependencies

```bash
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](https://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:

```bash
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

```bash
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:

```bash
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`](./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:

```bash
-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`](https://pypi.org/project/mcp/) Python SDK and runs as a stdio subprocess — no
network port, no daemon, nothing running when Claude Code isn't.

## License

[MIT](./LICENSE)