https://github.com/neuwcodebox/confluence-mcp
An MCP server that helps AI agents navigate Confluence like a human: discover, search, follow hierarchy, and read pages safely within context limits.
https://github.com/neuwcodebox/confluence-mcp
Last synced: 2 months ago
JSON representation
An MCP server that helps AI agents navigate Confluence like a human: discover, search, follow hierarchy, and read pages safely within context limits.
- Host: GitHub
- URL: https://github.com/neuwcodebox/confluence-mcp
- Owner: neuwcodebox
- Created: 2026-03-19T00:58:11.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-19T12:00:42.000Z (3 months ago)
- Last Synced: 2026-03-19T23:09:55.563Z (3 months ago)
- Language: Python
- Homepage:
- Size: 55.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# confluence-mcp
An MCP server that helps AI agents navigate Confluence like a human: discover, search, follow hierarchy, and read pages safely within context limits.
## Quick start
```bash
uv sync
uv run confluence-mcp
```
## Environment variables
The server auto-loads a local `.env` file on startup (via `python-dotenv`) for development convenience.
- `CONFLUENCE_BASE_URL` (required): e.g. `https://your-domain.atlassian.net/wiki`
- `MCP_AUTH_KEY` (optional): server access key. If set, incoming `Authorization` header must match this value.
- `CONFLUENCE_TOKEN` (optional): default Confluence API token. `X-Confluence-Token` request header takes precedence.
- `CONFLUENCE_API_VERSION` (optional): `v2` (default) or `v1` for legacy Confluence instances.
- `CONFLUENCE_SSL_VERIFY` (optional): TLS cert verification toggle (`true` default, set `false` to disable).
- `CONFLUENCE_CA_BUNDLE` (optional): path to a custom CA bundle file for TLS verification.
- `CONFLUENCE_CACHE_DIR` (optional): markdown cache directory (default `./cache`)
- `MAX_MARKDOWN_CHARS` (optional): max markdown body size after conversion (default `12000`)
- `IN_MEMORY_CACHE_TTL_SECONDS` (optional): API response cache TTL in seconds (default `1800`)
- `IN_MEMORY_CACHE_SIZE` (optional): API response cache size (default `1000`)
- `MCP_TRANSPORT` (optional): `stdio` or `streamable-http` (Docker default: `streamable-http`)
- `MCP_HOST` (optional): host for HTTP mode (`127.0.0.1`, Docker default `0.0.0.0`)
- `MCP_PORT` (optional): port for HTTP mode (`8000`)
### .env support
Example `.env`:
```dotenv
CONFLUENCE_BASE_URL=https://your-domain.atlassian.net/wiki
MCP_AUTH_KEY=your-mcp-auth-key
CONFLUENCE_TOKEN=your-default-confluence-token
CONFLUENCE_API_VERSION=v2
MCP_TRANSPORT=streamable-http
MCP_HOST=0.0.0.0
MCP_PORT=8000
# if needed for self-signed/private CA environments
CONFLUENCE_SSL_VERIFY=false
# or: CONFLUENCE_CA_BUNDLE=/path/to/ca-bundle.pem
```
## Tooling
All tools return both structured JSON (`structuredContent`) and human-readable markdown text (`content`).
- `search_space_cql`: searches pages with full CQL (including your `space = ...` condition) and returns absolute page URLs.
- `list_page_children`: returns direct children of a page and always includes parent title.
- `read_page`: returns markdown content (+TOC), cache metadata, truncation metadata, and optional section-focused view. `header_path` supports array-based hierarchical syntax (e.g., `["Top", "Child", "Target"]`). If a single name is duplicated, all matched sections are returned. For quick skim, set `header_path=["TOC"]`.
- `get_page_ancestors`: returns page breadcrumb lineage.
### search_space_cql quick examples
These go into the `cql` argument (the tool automatically adds `space = `):
- `type = "page"`
- `title ~ "release"`
- `text ~ "runbook"`
- `lastmodified >= "2024/01/01" ORDER BY lastmodified DESC`
- `creator = currentUser()`
- `label NOT IN (archived,obsolete)`
- `(type = "page" AND title ~ "api") OR (type = "blogpost" AND creator = currentUser())`
## Caching and content shaping
- Uses in-memory LRU+TTL cache for Confluence API responses (default: 1000 entries, 1800s TTL).
- Reads page version first, then uses cache key `page_id + version`.
- Cache hit: returns cached markdown immediately.
- Cache miss: fetches page body, converts HTML to markdown, stores to disk cache.
- Adds a generated TOC at the beginning of output.
- Supports section-focused reading via `header_path` option.
- If content exceeds limit, truncates and appends `...(truncated)`.
## Docker
```bash
docker build -t confluence-mcp .
docker run --rm -p 8000:8000 \
-e CONFLUENCE_BASE_URL="https://your-domain.atlassian.net/wiki" \
-e MCP_AUTH_KEY="your-mcp-auth-key" \
-e CONFLUENCE_TOKEN="your-default-confluence-token" \
-e MCP_TRANSPORT="streamable-http" \
-e MCP_HOST="0.0.0.0" \
-e MCP_PORT="8000" \
-v confluence-mcp-cache:/data/cache \
confluence-mcp
```