mcp-confluence-file-based

Translations: Russian, Spanish, Chinese.

This MCP server is designed for safe reading and editing of large Confluence pages in storage XHTML. Instead of sending the full body.storage.value directly into the LLM context, the server saves the XHTML body to a local file and returns only metadata plus the file path to the model.

This file-based flow reduces context overflow risk, helps with large tables and ac:structured-macro, and lowers the chance of accidentally breaking XML/macros during page updates. Writes are performed only from local XHTML files and protected with an expectedVersion check to avoid silent overwrites during concurrent edits.

The approach is especially useful for Confluence Data Center / On-Premise and corporate environments where PAT, self-signed TLS, and complex macro-heavy pages are common. 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.

Main Workflow

1. MCP client calls a tool, for example get_confluence_page, with pageId or pageUrl.
2. The server fetches page data from Confluence REST API.
3. For read operations, storage XHTML is saved into local cache (CONFLUENCE_CACHE_DIR or system temp), and the response returns metadata plus BodyFile.
4. LLM reads and edits XHTML in local files instead of inline payloads.
5. For writes, the client calls update_confluence_page or create_confluence_page with file paths (newContentFile / bodyStorageFile).

End-to-End Example

1) get_confluence_page(pageId=123)
   -> returns BodyFile=/.../mcpcfb-get-123-v17-....xhtml, Version=17

2) Edit that XHTML file locally (preserve valid storage XHTML/macros)

3) update_confluence_page(
     pageId=123,
     newContentFile=/.../mcpcfb-get-123-v17-....xhtml,
     expectedVersion=17
   )

If Confluence version changed in the meantime, the update is rejected; re-read the page and re-apply changes.

Why Storage XHTML in a File

• Confluence storage format reference: Confluence Storage Format (Atlassian)
• This MCP stores large XHTML bodies in local files so the model can inspect and edit focused fragments such as table, tr, and ac:structured-macro without pushing the whole page body into the chat context.

Tools

| Tool | Description | | --- | --- | | get_confluence_page | Fetch page and store body in cache file. | | list_confluence_child_pages | List direct child pages. | | create_confluence_page | Create a page from storage XHTML file. | | update_confluence_page | Update page from storage XHTML file with strict version check. | | move_confluence_page | Move page under a new parent with strict version check. | | list_confluence_page_labels | List labels on a page. | | add_confluence_page_labels | Add labels idempotently. | | remove_confluence_page_labels | Remove labels idempotently. |

Runtime Configuration (ENV)

| Variable | Required | Description | | --- | --- | --- | | CONFLUENCE_BASE_URL | Yes | Base URL, for example https://confluence.example.com. | | CONFLUENCE_PAT | Yes | Confluence Personal Access Token. | | CONFLUENCE_DEFAULT_PAGE_ID | No | Fallback page ID when a request does not include pageId or pageUrl. | | CONFLUENCE_INSECURE_TLS | No | Set to yes, true, or 1 only in trusted self-signed TLS environments. Any other value (or unset) is treated as false. The server logs a one-time startup warning when enabled. | | CONFLUENCE_CACHE_DIR | No | Absolute path for cached storage XHTML files. | | CONFLUENCE_CACHE_CLEANUP_INTERVAL_MS | No | Cache cleanup interval in milliseconds. Defaults to 60000. | | CONFLUENCE_BODY_FILE_MAX_BYTES | No | Symmetric read/write body-file limit in bytes. Default 0 means no hard cap (operator opt-in). | | CONFLUENCE_MAX_TOTAL_CHILD_PAGES | No | Hard cap for total child pages returned by list_confluence_child_pages. Defaults to 5000. |

Client Setup

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_DEFAULT_PAGE_ID": "123456789",
        "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.

Architecture

• dist/server.js - runtime entrypoint (compiled from TypeScript).
• src/*.ts - primary TypeScript source.
• dist/ - compiled TS runtime artifacts.

dist/ is a build artifact and is intentionally not committed to git. It is generated by npm run build and validated in CI/release checks.

Security Considerations

• Keep CONFLUENCE_PAT in environment variables only.
• Use CONFLUENCE_INSECURE_TLS=yes/true/1 only in trusted private environments; any other value is treated as false.
• Treat cache files as sensitive because they may contain private Confluence data.
• create/update read page bodies only from local files, not inline tool params.
• Default read/write body policy has no hard cap (CONFLUENCE_BODY_FILE_MAX_BYTES=0); operators can set an explicit limit when needed.
• update_confluence_page and move_confluence_page require expectedVersion and block mismatched writes.
• See SECURITY.md for detailed operator notes.

Documentation

• README.ru.md
• README.es.md
• README.zh.md
• SECURITY.md
• CONTRIBUTING.md
• CHANGELOG.md