# confluence-http-api-mcp

Read-only MCP server for **self-hosted Confluence** (Server / Data Center) over the REST API.

Primary use case: let an AI agent **read project documentation** — search pages, fetch content, navigate page trees.

## Requirements

- Node.js 18+
- Confluence base URL and a [Personal Access Token](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) with read access to the relevant spaces

## Configuration

| Variable           | Required | Description                                      |
|--------------------|----------|--------------------------------------------------|
| `CONFLUENCE_URL`   | Yes      | Base URL, e.g. `https://wiki.it-aces.com`       |
| `CONFLUENCE_TOKEN` | Yes      | PAT sent as `Authorization: Bearer …`           |

Alias: `CONFLUENCE_PAT`.

## Tools (read-only)

| Tool | Purpose |
|------|---------|
| `confluence_search` | CQL search (`space=GAR AND type=page`, `text ~ "API"`) |
| `confluence_get_page` | Page by content id + plain-text body |
| `confluence_get_page_by_title` | Page by space key + exact title |
| `confluence_list_spaces` | Discover spaces |
| `confluence_get_page_children` | Child pages (doc tree / TOC) |

Page bodies are returned as **plain text** (HTML/storage markup stripped) for easier agent consumption.

## Install

### From source (GitLab / GitHub)

```bash
git clone git@gitlab.greenworm.ru:ai/confluence-http-api-mcp.git
cd confluence-http-api-mcp
npm install
```

Публичное зеркало: `https://github.com/rkorablin/confluence-http-api-mcp`.

### From npm

```bash
npm install confluence-http-api-mcp
```

Or globally (for `npx` / CLI usage):

```bash
npm install -g confluence-http-api-mcp
```

## Usage

### Standalone (stdio)

```bash
export CONFLUENCE_URL="https://wiki.it-aces.com"
export CONFLUENCE_TOKEN="..."
node server.mjs
```

## Cursor / MCP host

Add the server to your MCP config (for example `.cursor/mcp.json` → `mcpServers`).

#### Option 1: Local clone

```json
"confluence": {
  "command": "node",
  "args": ["/absolute/path/to/confluence-http-api-mcp/server.mjs"],
  "env": {
    "CONFLUENCE_URL": "https://wiki.it-aces.com",
    "CONFLUENCE_TOKEN": "..."
  }
}
```

#### Option 2: npm / npx

If installed globally:

```json
"confluence": {
  "command": "confluence-http-api-mcp",
  "env": {
    "CONFLUENCE_URL": "https://wiki.it-aces.com",
    "CONFLUENCE_TOKEN": "..."
  }
}
```

Or via `npx` (рекомендуется для автоподтягивания новых версий):

```json
"confluence": {
  "command": "npx",
  "args": ["--yes", "--prefer-online", "confluence-http-api-mcp@latest"],
  "env": {
    "CONFLUENCE_URL": "https://wiki.it-aces.com",
    "CONFLUENCE_TOKEN": "..."
  }
}
```

Or via wrapper + secrets file (see `~/.config/ai-mcp` pattern used for GitLab/YouTrack).

## Typical agent workflow

1. `confluence_list_spaces` — find space key (e.g. `GAR`)
2. `confluence_search` with `space=GAR AND title ~ "Architecture"`
3. `confluence_get_page` — read full page text
4. `confluence_get_page_children` — walk documentation hierarchy

## License

MIT