# 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`):

```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](https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html) (XHTML-based), for example `<p>Hello world</p>`.

## Install and run

```bash
npm install
npm run build
npm start
```

Development mode:

```bash
npm run dev
```

Smoke test:

```bash
npm run test:confluence
```

## MCP client config example

```json
{
	"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:

```json
{ "pageId": "123456" }
```

By space + title:

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

### `confluence_search`

Input:

```json
{
	"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:

```json
{
	"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.

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

### `confluence_add_comment`

Input:

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

### `confluence_list_spaces`

Input:

```json
{ "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.