mcp-confluence-file-based

Translations: Russian, Spanish, Chinese.

This MCP server lets an AI assistant (in Cursor, Claude Desktop, or any MCP-enabled tool) safely read and edit Confluence pages — including the large, macro-heavy ones that usually break.

Teams keep requirements, specs, and project documentation in Confluence. When an AI assistant works with those pages directly, two things tend to go wrong: big pages with tables and macros get garbled or truncated, and a colleague's concurrent edit can be silently overwritten. This server avoids both. Instead of pushing the whole page through the chat, it saves the page body — Confluence's internal storage XHTML format — into a local file. The assistant edits that file and publishes it back only after a version check, so nobody's work is silently lost.

What this gives you in practice:

• Pages of any size. The page body never floods the chat context, so huge tables and long documents stay workable.
• Formatting survives. Tables and Confluence macros (ac:structured-macro) are edited as local files instead of being retyped by the model inline.
• No silent overwrites. If someone changed the page while you were editing, the update is rejected (VersionMismatch) — re-read the page and re-apply your changes.
• Corporate-ready. Built for Confluence Data Center / On-Premise: PAT authentication, self-signed TLS support.

If you need broad read-only search across Confluence Cloud, comments, or integration with Atlassian cloud capabilities, a broader MCP server may be a better fit.

Example Workflow

In short: the assistant fetches a page into a local XHTML file, edits and re-checks that file locally, and publishes it back through the server with a strict version check — the page body itself never travels through the chat.

1. The user asks the AI assistant in plain language, for example: "Update the release notes page".
2. The assistant calls the get_confluence_page tool with pageId or pageUrl.
3. The MCP server requests the page from the Confluence REST API.
4. Confluence returns the page data: metadata, the current version (say, 17), and the body in storage XHTML — Confluence's internal page format.
5. The server saves the page body into a local cache file (CONFLUENCE_CACHE_DIR or system temp).
6. The cache file is confirmed saved.
7. The assistant receives structuredContent with metadata and the file path only — for example { "pageId": "123", "version": 17, "bodyFile": "/.../mcpcfb-get-123-v17-....xhtml", "bodySha256": "..." } — so the chat context stays small no matter how big the page is.
8. The assistant edits only the needed fragment in the file — a table row, an ac:structured-macro, a paragraph — without retyping the whole page inline.
9. The assistant re-reads the file and self-checks the result (valid XML, intact macros); steps 8–9 repeat until the edit is complete.
10. The assistant calls update_confluence_page with the bodyFile path and expectedVersion (17); create_confluence_page works the same way for new pages.
11. The server reads the body file from disk.
12. The file content is loaded — page bodies are accepted only from local files, never from inline tool parameters.
13. The server checks the page version and publishes the new body to Confluence.
14. Confluence confirms the publication: new version 18.
15. The server returns the confirmation to the assistant, for example { "pageId": "123", "currentVersion": 17, "version": 18, ... }.
16. The assistant reports back to the user: done, the new version is published.

If someone changed the page between steps 7 and 13, the version check fails and the update is rejected with a VersionMismatch error — the assistant re-reads the page and re-applies the changes, so nobody's work is overwritten silently.

Tools

| Tool | Description | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | add_confluence_page_labels | Add labels to a page idempotently. | | create_confluence_page | Create a page from a local storage XHTML bodyFile. | | get_confluence_page | Fetch a page and store its body in a local bodyFile. | | list_confluence_child_pages | List direct child pages. | | list_confluence_page_attachments | List attachment metadata for a page (up to 100, no binary or download URLs). | | list_confluence_page_labels | List labels on a page. | | list_confluence_pages | List pages via structured allowlist filters (space, dates, title, label, parent/ancestor) with server-built CQL. | | move_confluence_page | Move a page under a new parent with strict version check. | | remove_confluence_page_labels | Remove labels from a page idempotently. | | update_confluence_page | Update a page from a local bodyFile with strict version check. | | upload_confluence_page_attachment | Upload a local file as a page attachment, creating it or a new version of an existing filename. |

Quick Start

1. Get a Confluence token. Ask your Confluence administrator for a Personal Access Token (PAT), or create one yourself: in Confluence, open your profile → Personal Access Tokens → create a token.
2. Connect the server to your AI assistant. Copy the JSON snippet below into your assistant's MCP configuration (Cursor, Claude Desktop, or another MCP-enabled client) and fill in your Confluence URL and the token. Node.js 20+ must be installed; if unsure, ask your IT team.
3. Check it works. Ask the assistant: "Show me this Confluence page: <paste a page link>". It should fetch the page and describe it.

Runtime Configuration (ENV)

• CONFLUENCE_BASE_URL (required) — root URL of your Confluence instance, for example https://confluence.example.com.
• CONFLUENCE_PAT (required) — Confluence Personal Access Token the server authenticates with.
• CONFLUENCE_INSECURE_TLS — set to true only for trusted self-signed TLS environments.
• CONFLUENCE_CACHE_DIR — where page bodies are cached locally; treat as sensitive (defaults to system temp).
• CONFLUENCE_TEXT_CONTENT_COMPAT — set to true only if your AI assistant sees empty results for successful calls (legacy MCP clients that do not read structuredContent).
• All variables, defaults, and practical examples: see the runtime configuration reference.

npx (recommended)

{
  "mcpServers": {
    "confluence": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-confluence-file-based"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://confluence.example.com",
        "CONFLUENCE_PAT": "YOUR_PAT",
        "CONFLUENCE_INSECURE_TLS": "false",
        "CONFLUENCE_CACHE_DIR": "/tmp/mcp-confluence-cache",
        "CONFLUENCE_CACHE_CLEANUP_INTERVAL_MS": "60000"
      }
    }
  }
}

Local run from sources

npm ci
npm start

Requires Node.js >=20.

For explicit client config, run dist/server.js with node and pass the same ENV values.

Security Considerations

The PAT stays in environment variables and is never written to disk by the server. Cached page bodies may contain private Confluence content — treat the cache directory as sensitive. Writes happen only from local files and only after an expectedVersion check. Full operator guidance and the threat model: SECURITY.md.

Documentation

• README.ru.md
• README.es.md
• README.zh.md
• Runtime configuration reference
• Tool result contracts
• Troubleshooting
• SECURITY.md
• CONTRIBUTING.md
• CHANGELOG.md