Metadata-Version: 2.4
Name: www-confluence-mcp
Version: 1.1.2
Summary: MCP server providing Confluence Server/Data Center integration: page management, search, spaces, and more.
Project-URL: Homepage, https://github.com/naifs/www-confluence-mcp
Project-URL: Repository, https://github.com/naifs/www-confluence-mcp
Project-URL: Issues, https://github.com/naifs/www-confluence-mcp/issues
Author-email: Naifs <naifs.rage@gmail.com>
License: MIT
License-File: LICENSE
Keywords: atlassian,confluence,mcp,wiki,www-confluence-mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: idna>=3.15
Requires-Dist: lxml>=6.1.0
Requires-Dist: markdown>=3.5
Requires-Dist: mcp>=1.26.0
Requires-Dist: niquests>=3.18.8
Requires-Dist: parsel>=1.11.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: truststore>=0.10.4
Requires-Dist: uvicorn>=0.46.0
Description-Content-Type: text/markdown

# www-confluence-mcp

MCP (Model Context Protocol) server providing **Confluence Server/Data Center** integration — page management, search, spaces, comments, labels, attachments, and more.

Gives AI assistants (Qoder, Claude Desktop, Cursor, etc.) the ability to read and write Confluence content through a single MCP server with **25 tools** (24 tools + 1 prompt tool) and **2 built-in prompts**.

> **Note:** This server targets **Confluence Server/Data Center** only (v1 REST API). Confluence Cloud is not supported.

## System Requirements

| Requirement | Version |
|---|---|
| **uv** | [Install guide](https://docs.astral.sh/uv/getting-started/installation/) |
| **Python** | 3.10+ (managed automatically by `uv`) |
| **Confluence** | Server 5.6+ / Data Center 6.0+ |

### Install uv

**macOS / Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**macOS (Homebrew):**
```bash
brew install uv
```

## Installation

### Option 1: From PyPI (recommended)

**uvx — one-shot run, auto-updates on every launch:**

```bash
uvx www-confluence-mcp
```

**uv tool install — persistent global command:**

```bash
# Install (or update to latest):
uv tool install --force www-confluence-mcp@latest

# Run:
www-confluence-mcp

# Update later:
uv tool install --force www-confluence-mcp@latest
```

### Option 2: From source or wheel (development)

```bash
git clone https://github.com/naifs/www-confluence-mcp.git
cd www-confluence-mcp
uv sync

# Run directly:
uv run www-confluence-mcp

# Or build and install as a global command:
uv build
uv tool install --force dist/*.whl

# Update later:
git pull && uv sync
# or rebuild:
uv build && uv tool install --force dist/*.whl
```

## MCP Client Config

All variants share the same `env` block. The only difference is `command` and `args`:

```jsonc
{
  "mcpServers": {
    "www-confluence-mcp": {

      // Option 1a: uvx — ephemeral run from PyPI, auto-updates on each launch
      "command": "uvx",
      "args": ["www-confluence-mcp"],

      // Option 1b: uv tool install — globally installed command, no args needed
      // "command": "www-confluence-mcp",
      // "args": [],

      // Option 2: local source — run from a cloned repo (replace path)
      // "command": "uv",
      // "args": ["run", "--project", "/absolute/path/to/www-confluence-mcp", "www-confluence-mcp"],

      "env": {
        "CONFLUENCE_URL": "https://confluence.example.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your-pat-here"
      }
    }
  }
}
```

**How to use:** uncomment exactly one of the `command`/`args` pairs above and delete the rest.

## Authentication

The server supports two authentication methods for Confluence Server/Data Center:

| Method | Environment Variables |
|---|---|
| **Personal Access Token (PAT)** (recommended) | `CONFLUENCE_PERSONAL_TOKEN` |
| **Basic Auth** (username + password) | `CONFLUENCE_USERNAME` + `CONFLUENCE_PASSWORD` |

PAT takes priority if both are configured. `CONFLUENCE_API_TOKEN` is accepted as a legacy fallback for `CONFLUENCE_PASSWORD`.

## Environment Variables

| Variable | Description | Default |
|----------|-------------|--------|
| `CONFLUENCE_URL` | Confluence Server/DC base URL (required) | — |
| `CONFLUENCE_PERSONAL_TOKEN` | Personal Access Token for PAT auth | — |
| `CONFLUENCE_USERNAME` | Username for Basic auth | — |
| `CONFLUENCE_PASSWORD` | Password for Basic auth | — |
| `CONFLUENCE_SSL_VERIFY` | Verify TLS certificates (system trust store via `truststore`) | `true` |
| `CONFLUENCE_SSL_PATH` | Optional path to extra CA certs (PEM file or OpenSSL-hashed dir), loaded **in addition to** the system trust store | — |
| `CONFLUENCE_TIMEOUT` | HTTP request timeout in seconds | `30` |
| `CONFLUENCE_MAX_RESULTS` | Default max results per query (1..100) | `25` |
| `CONFLUENCE_READ_ONLY` | Disable write tools (`true`/`false`) | `true` |
| `CONFLUENCE_SPACES_FILTER` | Comma-separated space keys to filter searches | — |
| `CONFLUENCE_HTTP_PROXY` | HTTP proxy URL | — |
| `CONFLUENCE_HTTPS_PROXY` | HTTPS proxy URL | — |
| `CONFLUENCE_DEBUG` | Enable debug logging (`1`/`true`/`yes`/`on`) | `false` |
| `CONFLUENCE_PROMPTS_DIR` | Custom prompts directory for YAML prompts | — |
| `CONFLUENCE_RATE_LIMIT_TOKENS` | Rate limiter: tokens per second (client-side) | `10.0` |
| `CONFLUENCE_RATE_LIMIT_BURST` | Rate limiter: max burst tokens | `20` |
| `CONFLUENCE_MCP_TRANSPORT` | Transport mode: `stdio` (local) or `http` (remote) | `stdio` |
| `CONFLUENCE_MCP_HOST` | HTTP server bind address (when `TRANSPORT=http`) | `127.0.0.1` |
| `CONFLUENCE_MCP_PORT` | HTTP server port (when `TRANSPORT=http`) | `8080` |

## Provided Tools

### Read Tools (14)

- **`confluence_search`** — Search content by text or CQL query
- **`confluence_get_page`** — Get page by ID or URL (saves to `{workspace}/tmp/page_{page_id}.md`)
- **`confluence_get_page_ancestors`** — Get ancestor pages (breadcrumb)
- **`confluence_get_spaces`** — List all spaces or get one by key
- **`confluence_get_pages`** — Get pages from a space (tree) or children of a page
- **`confluence_get_page_comments`** — Get page comments
- **`confluence_get_page_labels`** — Get page labels
- **`confluence_get_page_attachments`** — List page attachments
- **`confluence_download_attachments`** — Download attachments to disk (all or by IDs, saves to `{workspace}/tmp/`)
- **`confluence_get_page_history`** — Get page version history
- **`confluence_get_page_images`** — Get page images as base64
- **`confluence_get_user`** — Search for users by username, email, or display name
- **`confluence_validate_page`** — Validate Confluence page with XHTML validation and round-trip checking
- **`confluence_mcp_info`** — Get server configuration info (all environment variables, defaults, examples)
- **`confluence_mcp_health`** — Health check (server status, uptime, version, tool count, connection status)

### Write Tools (10) — only when `CONFLUENCE_READ_ONLY=false`

- **`confluence_new_page`** — Create a new page
- **`confluence_update_page`** — Update an existing page
- **`confluence_delete_pages`** — Delete multiple pages in batch
- **`confluence_move_page`** — Move page to another space/parent
- **`confluence_add_comment`** — Add a comment to a page
- **`confluence_add_labels`** — Add labels to a page
- **`confluence_delete_labels`** — Delete multiple labels from multiple pages in batch
- **`confluence_upload_attachments`** — Upload one or more files as attachments
- **`confluence_delete_attachments`** — Delete multiple attachments in batch

### Prompt Tool (1)

- **`confluence_mcp_prompts`** — List all loaded external prompt definitions, or get full prompt content by name

## Built-in Prompts

The server includes 2 built-in prompts accessible via `confluence_mcp_prompts`:

- **`update_page_from_template`** — Merge source content with a template (supports IN-PLACE update or NEW PAGE creation)
- **`how_to_write_prompts`** — Guide for creating YAML prompt definitions

Prompts are loaded from the builtin prompts directory and can be extended with custom prompts via `CONFLUENCE_PROMPTS_DIR`.

## Remote Deployment (HTTP Mode)

The server supports running as a remote HTTP service, allowing multiple users to connect with their own Confluence credentials.

### Quick Start

```bash
# Start in HTTP mode
CONFLUENCE_MCP_TRANSPORT=http \
CONFLUENCE_URL=https://confluence.example.com \
uvx www-confluence-mcp
```

The server listens on `127.0.0.1:8080` by default. Set `CONFLUENCE_MCP_HOST=0.0.0.0` to expose externally.

### Client Configuration

Users connect by passing their credentials as HTTP headers — **the same env var names** used locally:

```jsonc
{
  "mcpServers": {
    "confluence": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "CONFLUENCE_URL": "https://confluence.example.com",
        "CONFLUENCE_PERSONAL_TOKEN": "user-pat-token"
      }
    }
  }
}
```

This works identically to local mode — the only difference is credentials go in headers instead of env vars.

### How It Works

1. **Local mode (stdio):** Credentials come from environment variables → shared singleton HTTP client (unchanged behavior)
2. **Remote mode (HTTP):** Credentials come from request headers → per-user cached HTTP client (1-hour TTL)

Each user gets their own isolated Confluence session. Clients are cached to avoid recreating connections on every request.

### Production Deployment

```bash
# Run with uvicorn (recommended for production)
CONFLUENCE_MCP_TRANSPORT=http \
CONFLUENCE_MCP_HOST=0.0.0.0 \
CONFLUENCE_MCP_PORT=8080 \
uv run www-confluence-mcp
```

Behind a reverse proxy (nginx):

```nginx
server {
    listen 443 ssl;
    server_name mcp.example.com;

    location /mcp {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
}
```

## Troubleshooting

### `uv` not found
Install `uv` and reopen your terminal. See [System Requirements](#system-requirements).

### Dependencies missing
```bash
uv sync
```

### MCP tools not appearing in client
1. Check that the MCP client config JSON is valid.
2. Ensure the `--project` path is absolute and correct.
3. Reload the MCP client after config changes.
4. Check `CONFLUENCE_DEBUG=true` for detailed logs.

### Authentication error
- Verify `CONFLUENCE_URL` points to your Server/DC instance (not `*.atlassian.net`).
- For PAT: ensure the token is valid and not expired.
- For Basic auth: ensure both `CONFLUENCE_USERNAME` and `CONFLUENCE_API_TOKEN` are set.

### Wrong project path in config
The `--project` argument must point to the **root directory** of `www-confluence-mcp` (where `pyproject.toml` is located), not to the `src/` subdirectory.

### Rate limiting errors (429)
The server includes built-in client-side rate limiting to prevent hitting Confluence's limits. Defaults: 10 tokens/second, burst of 20. Tune with `CONFLUENCE_RATE_LIMIT_TOKENS` and `CONFLUENCE_RATE_LIMIT_BURST`.

## License

MIT
