Confluence ADF MCP 服务器

confluence-adf-mcp

MCP server for reading and writing Confluence pages in native ADF (Atlassian Document Format).

Why this exists

Confluence stores pages in ADF (Atlassian Document Format), a structured JSON format. Most tools convert to/from HTML or plain text, losing structure, formatting, and metadata in the process. This MCP server works with ADF directly, so edits are precise — find/replace, table updates, and mention swaps happen at the document node level without corrupting the surrounding content.

Setup

Requirements

• Python 3.12+
• A Confluence Cloud instance with API access

Environment variables

export CONFLUENCE_URL="https://your-domain.atlassian.net/wiki"
export CONFLUENCE_USERNAME="you@example.com"
export CONFLUENCE_API_TOKEN="your-api-token"

Generate an API token at https://id.atlassian.com/manage-profile/security/api-tokens.

OAuth 2.0 (optional)

Instead of basic auth, you can use OAuth 2.0 (3LO). Set these three environment variables:

export CONFLUENCE_OAUTH_CLIENT_ID="your-oauth-client-id"
export CONFLUENCE_OAUTH_CLIENT_SECRET="your-oauth-client-secret"
export CONFLUENCE_OAUTH_REFRESH_TOKEN="your-initial-refresh-token"

If all three are set, the server uses OAuth automatically; otherwise it falls back to basic auth (CONFLUENCE_USERNAME / CONFLUENCE_API_TOKEN).

Rotating refresh tokens are persisted to .oauth_tokens.json in the cache directory so the server can restart without re-authorizing. The cache directory defaults to $XDG_CACHE_HOME/confluence-adf-mcp (or ~/.cache/confluence-adf-mcp); set CACHE_DIR to override it.

See Atlassian OAuth 2.0 (3LO) documentation for how to create an OAuth app and obtain the initial refresh token.

Claude Code configuration

Copy .env.example to .env and fill in your credentials. The server loads .env automatically.

Add to .claude/settings.json:

{
  "mcpServers": {
    "confluence-adf": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/karbassi/confluence-adf-mcp", "confluence-adf-mcp"]
    }
  }
}

Shared HTTP server

By default every client starts its own stdio process. To run one long-lived server that many clients share:

CONFLUENCE_ADF_MCP_TRANSPORT=http CONFLUENCE_ADF_MCP_PORT=8506 confluence-adf-mcp

{
  "mcpServers": {
    "confluence-adf": { "type": "http", "url": "http://127.0.0.1:8506/mcp" }
  }
}

FASTMCP_HOST / FASTMCP_PORT have no effect; use the variables above.

The endpoint has no authentication. It holds your Atlassian credentials, and its tools can edit, move, archive, and restrict pages and delete attachments. Anything that can connect to it acts as you. So:

• The server only binds to loopback. Any local process can still connect, so only use HTTP mode on a machine where every local user and process is trusted with your Atlassian account.
• DNS-rebinding protection is always on: requests whose Host is not 127.0.0.1:<port>, localhost:<port> (or an entry in CONFLUENCE_ADF_MCP_ALLOWED_HOSTS) are rejected with 421, and cross-site Origins with 403. That check only stops web pages from reaching the server through a rebound DNS name. It does not authenticate anyone.
• To reach it from another machine, put it behind a reverse proxy that controls who can connect (bearer token, mTLS, an IP allowlist on a private network, or similar) and add the proxy's hostname to CONFLUENCE_ADF_MCP_ALLOWED_HOSTS. Never expose the port or the proxy publicly without access control.

File paths always refer to the filesystem of the machine running the server, not the client's:

• confluence_get_page returns the absolute path of the cached copy to edit. A remote client can't open it, so use the edit tools (confluence_edit_page, confluence_find_replace, ...) instead of editing the file directly.
• confluence_upload_attachment reads, and confluence_download_attachment writes, paths on the server machine.

Each MCP session gets its own page cache under <cache dir>/sessions/<session>/, so clients sharing one server can't see, overwrite, or clear each other's cached pages. If a client reconnects it gets a new session, so call confluence_get_page again before editing. Session directories untouched for CONFLUENCE_ADF_MCP_CACHE_TTL_HOURS (default 168, i.e. 7 days; 0 disables) are deleted at startup and at most hourly while the server runs.

Tools

Pages

Editing

Tables

Tasks

Discovery

Labels

Versions

Comments

Attachments

Properties

Access Control

Cache

Contributing

See CONTRIBUTING.md.