confluence-mcp

A local MCP server for Confluence (Data Center/Server compatible) with token-based auth.

This server exposes a compact set of tools for page lookup, CQL search, page creation/updates, comments, and space discovery.

What this server provides

• confluence_get_page — get a page by ID, or by spaceKey + title
• confluence_search — search content with CQL
• confluence_create_page — create a page
• confluence_update_page — update a page's title/body (auto-increments version)
• confluence_add_comment — add a comment to a page
• confluence_list_spaces — list spaces (useful to discover space keys)

Requirements

• Node.js >=20
• Confluence account with API access
• Space/page permissions matching your actions (create, update, comment, etc.)

Configuration

Set environment variables (for example in .env):

# Required
CONFLUENCE_BASE_URL=https://your-confluence-host

# Optional (defaults shown)
CONFLUENCE_AUTH_TYPE=bearer
CONFLUENCE_DEFAULT_SPACE_KEY=

# For bearer auth (Data Center/Server personal access token)
CONFLUENCE_PAT=

# For basic auth (Confluence Cloud email + API token)
CONFLUENCE_EMAIL=
CONFLUENCE_API_TOKEN=

Auth modes

• CONFLUENCE_AUTH_TYPE=bearer (default)
  • Requires CONFLUENCE_PAT (Data Center/Server personal access token)
• CONFLUENCE_AUTH_TYPE=basic
  • Requires CONFLUENCE_EMAIL + CONFLUENCE_API_TOKEN

Page and comment bodies use Confluence storage format (XHTML-based), for example <p>Hello world</p>.

Install and run

npm install
npm run build
npm start

Development mode:

npm run dev

Smoke test:

npm run test:confluence

MCP client config example

{
	"mcpServers": {
		"confluence": {
			"command": "node",
			"args": ["/absolute/path/to/confluence-mcp/dist/index.js"],
			"env": {
				"CONFLUENCE_BASE_URL": "https://confluence.your-company.local",
				"CONFLUENCE_AUTH_TYPE": "bearer",
				"CONFLUENCE_PAT": "your-personal-access-token",
				"CONFLUENCE_DEFAULT_SPACE_KEY": "YOUR_SPACE_KEY"
			}
		}
	}
}

Tool inputs

confluence_get_page

By ID:

{ "pageId": "123456" }

By space + title:

{ "spaceKey": "YOUR_SPACE_KEY", "title": "Sprint Planning Notes" }

confluence_search

Input:

{
	"cql": "space = YOUR_SPACE_KEY AND type = page ORDER BY lastmodified DESC",
	"start": 0,
	"limit": 20
}

confluence_create_page

Required fields:

• title
• body (storage format)

Optional fields:

• spaceKey (falls back to CONFLUENCE_DEFAULT_SPACE_KEY)
• parentId (create as a child page)

Example input:

{
	"title": "[MCP] Example page",
	"body": "<p>Created from confluence-mcp</p>",
	"parentId": "123456"
}

confluence_update_page

Provide at least one of title or body. The current version is fetched automatically and incremented.

{
	"pageId": "123456",
	"body": "<p>Updated content</p>"
}

confluence_add_comment

Input:

{
	"pageId": "123456",
	"comment": "<p>Investigation started</p>"
}

confluence_list_spaces

Input:

{ "limit": 25 }

Troubleshooting

• Update fails with version conflict (409)

  • Another edit happened concurrently. Re-fetch the page (confluence_get_page) and retry.

• Create page fails with space permission errors (403)

  • These are Confluence permission-scheme restrictions for your user/token, not MCP runtime errors.

• CQL search returns no results

  • Confirm the space key casing and that type = page (or type = comment, etc.) matches what you expect.