npm package: @lvasko/confluence-rw-mcp
Description: Read-write MCP server for Confluence with read/write allowlists
Latest version: 1.1.0

# Confluence RW MCP

Windows-friendly stdio MCP server for Confluence with separate read and write allowlists.

Supports:

- Confluence Cloud with Atlassian account email + API token
- on-prem / Data Center with bearer PAT auth

Write access is explicit. Read access is the union of:

- `CONFU_ALLOWED_READ_PAGE_IDS`
- `CONFU_ALLOWED_WRITE_PAGE_IDS`

If a page is write-allowed, it is also automatically read-allowed.

## Requirements

- Windows
- Node.js
- PowerShell 7 or Windows PowerShell

If PowerShell 7 is not installed, secret resolution falls back to standard Windows PowerShell automatically through `@lvasko/local-secret-store`.

## Configuration

Environment variables:

- `CONFU_BASE_URL` required, for example `https://confluence.client.local`
- `CONFU_DEPLOYMENT_TYPE` preferred, `CLOUD` or `ON_PREM`
- `CONFU_PAT_SECRET_NAME` preferred for `ON_PREM`
- `CONFU_PAT` optional fallback for `ON_PREM`
- `CONFU_EMAIL` required for `CLOUD`
- `CONFU_API_TOKEN_SECRET_NAME` preferred for `CLOUD`
- `CONFU_API_TOKEN` optional fallback for `CLOUD`
- `CONFU_CERT_PATH` optional CA path for self-signed cert chains
- `CONFU_ALLOWED_READ_PAGE_IDS` required unless the write allowlist already provides pages
- `CONFU_ALLOWED_WRITE_PAGE_IDS` optional, required only if you want write access
- `CONFU_REQUEST_TIMEOUT_MS` optional, default `15000`
- `CONFU_MCP_CONFIG` optional explicit JSON config path

`CONFU_DEPLOYMENT_TYPE` is the normal user-facing setting:

- `CLOUD` implies `basic` auth
- `ON_PREM` implies `bearer` auth

`CONFU_AUTH_MODE` still works as an advanced override, but most users should not need it.

The server does not read `config.json` from the current working directory by default. A JSON config file is only used when you explicitly set `CONFU_MCP_CONFIG`.

Example `.codex/config.toml` for on-prem:

```toml
[mcp_servers.confluence-rw]
command = "npx"
args = ["-y", "@lvasko/confluence-rw-mcp@latest"]

[mcp_servers.confluence-rw.env]
CONFU_BASE_URL = "https://confluence.client.local"
CONFU_DEPLOYMENT_TYPE = "ON_PREM"
CONFU_PAT_SECRET_NAME = "confluence-client-pat"
CONFU_CERT_PATH = "C:\\certs\\client-ca.crt"
CONFU_ALLOWED_READ_PAGE_IDS = '["123456","234567"]'
CONFU_ALLOWED_WRITE_PAGE_IDS = '["345678"]'
```

Example `.codex/config.toml` for Atlassian Cloud:

```toml
[mcp_servers.confluence-cloud-rw]
command = "npx"
args = ["-y", "@lvasko/confluence-rw-mcp@latest"]

[mcp_servers.confluence-cloud-rw.env]
CONFU_BASE_URL = "https://example.atlassian.net"
CONFU_DEPLOYMENT_TYPE = "CLOUD"
CONFU_EMAIL = "user@example.com"
CONFU_API_TOKEN_SECRET_NAME = "confluence-cloud-api-token"
CONFU_ALLOWED_READ_PAGE_IDS = '["123456789"]'
CONFU_ALLOWED_WRITE_PAGE_IDS = '["987654321"]'
```

Example explicit JSON config:

```powershell
$env:CONFU_MCP_CONFIG = "C:\path\to\config.json"
```

```json
{
  "baseUrl": "https://confluence.client.local",
  "deploymentType": "ON_PREM",
  "patSecretName": "confluence-client-pat",
  "certPath": "C:\\certs\\client-ca.crt",
  "readAllowedPageIds": ["123456", "234567"],
  "writeAllowedPageIds": ["345678"]
}
```

## Tools

- `get_confluence_page_by_id`
- `get_confluence_page_from_url`
- `list_allowed_confluence_pages`
- `update_confluence_page_by_id`
- `update_confluence_page_from_url`
- `list_confluence_page_comments_by_id`
- `list_confluence_page_comments_from_url`
- `create_confluence_page_comment_by_id`
- `create_confluence_page_comment_from_url`
- `list_confluence_page_attachments_by_id`
- `list_confluence_page_attachments_from_url`
- `get_confluence_attachment_by_id`
- `get_confluence_attachment_from_url`
- `upload_confluence_attachment_by_id`
- `upload_confluence_attachment_from_url`

## Update Behavior

Updates use the current page version and send a new `body.storage` value with `version.number + 1`.
The page title is preserved unless a new `title` is provided.

Comments use the same storage-format HTML model as page updates.

Attachment reads return metadata plus full file content as base64.
Attachment uploads accept `filename`, `contentBase64`, and optional `contentType` and `comment`.

## Smoke Test

From the monorepo checkout you can validate config parsing with:

```powershell
npm run --workspace ./packages/confluence-rw-mcp smoke:config
```

The smoke test verifies:

- Cloud config infers `/wiki` and `basic` auth correctly
- on-prem config infers `bearer` auth correctly
- a stray working-directory `config.json` is ignored
- an explicit `CONFU_MCP_CONFIG` path is honored

## Notes

- The server fails closed if there are no allowed page IDs.
- URL-based reads and writes only work for the configured Confluence host.
- For Atlassian Cloud base URLs like `https://example.atlassian.net`, the server automatically normalizes the API base to `https://example.atlassian.net/wiki`.
- Comments and attachments follow the same page allowlist model: read on effective read allowlist pages, write on write allowlist pages.