Metadata-Version: 2.4
Name: www-confluence-mcp
Version: 1.0.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: httpx>=0.27.0
Requires-Dist: mcp>=1.26.0
Requires-Dist: truststore>=0.10.4
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.

> **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: Run directly with `uvx` (recommended)

No clone needed. Runs from PyPI. Updates automatically on each run:

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

MCP client config:

```json
{
  "mcpServers": {
    "www-confluence-mcp": {
      "command": "uvx",
      "args": ["www-confluence-mcp"],
      "env": {
        "CONFLUENCE_URL": "https://confluence.example.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your-pat-here"
      }
    }
  }
}
```

### Option 2: Install as a `uv tool`

```bash
# From PyPI
uv tool install www-confluence-mcp

# After installation, the command is available globally:
www-confluence-mcp
```

To update or reinstall:

```bash
uv tool upgrade www-confluence-mcp
# or force reinstall latest:
uv tool install --force www-confluence-mcp@latest
```

### Option 3: Run from local source (for development)

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

To update:

```bash
git pull && uv sync
```

MCP client config (local source):

```json
{
  "mcpServers": {
    "www-confluence-mcp": {
      "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"
      }
    }
  }
}
```

### Option 4: Install from built wheel

```bash
cd /path/to/www-confluence-mcp
uv build
uv tool install dist/*.whl
```

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

## Provided Tools

### Read Tools (15)

- **`confluence_search`** — Search content by text or CQL query
- **`confluence_get_page`** — Get page by ID, title+space_key, or URL
- **`confluence_get_page_children`** — Get child pages
- **`confluence_get_page_ancestors`** — Get ancestor pages (breadcrumb)
- **`confluence_get_spaces`** — List spaces
- **`confluence_get_space`** — Get space by key
- **`confluence_get_pages_in_space`** — List pages in a space
- **`confluence_get_comments`** — Get page comments
- **`confluence_get_labels`** — Get page labels
- **`confluence_get_attachments`** — List page attachments
- **`confluence_download_attachment`** — Download a single attachment
- **`confluence_download_content_attachments`** — Download all attachments
- **`confluence_get_page_history`** — Get page version history
- **`confluence_get_space_page_tree`** — Get space page hierarchy
- **`confluence_get_page_images`** — Get page images as base64
- **`confluence_search_user`** — Search for users

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

- **`confluence_create_page`** — Create a new page
- **`confluence_update_page`** — Update an existing page
- **`confluence_delete_page`** — Delete a page
- **`confluence_move_page`** — Move page to another space/parent
- **`confluence_add_comment`** — Add a comment
- **`confluence_reply_to_comment`** — Reply to a comment
- **`confluence_add_labels`** — Add labels to a page
- **`confluence_delete_label`** — Remove a label
- **`confluence_upload_attachment`** — Upload a file
- **`confluence_upload_attachments`** — Upload multiple files
- **`confluence_delete_attachment`** — Delete an attachment

## Quick Verification

```bash
# Search Confluence
CONFLUENCE_URL=https://confluence.example.com CONFLUENCE_PERSONAL_TOKEN=your-token \
uv run python -c "
import asyncio
from www_confluence_mcp.server import mcp
asyncio.run(mcp.run(transport='stdio'))
"

# Or just run the server
CONFLUENCE_URL=https://confluence.example.com CONFLUENCE_PERSONAL_TOKEN=your-token \
uv run www-confluence-mcp
```

## 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.

## License

MIT