confluence-mini-mcp
Lightweight MCP server that crawls Confluence subtrees and serves cached Markdown. Works with Claude Code and nanobot (Slack) via stdio.
Claude Code config
{
"mcpServers": {
"confluence-docs": {
"command": "uvx",
"args": ["--from", "git+https://github.com/bonkey/confluence-mini-mcp", "confluence-mini-mcp"],
"env": {
"CONFLUENCE_BASE_URL": "https://company.atlassian.net/wiki",
"CONFLUENCE_EMAIL": "you@company.com",
"CONFLUENCE_API_TOKEN": "...",
"CONFLUENCE_ROOT_PAGE_IDS": "123456,789012"
}
}
}
}Pin to a tag: "--from", "git+https://github.com/bonkey/confluence-mini-mcp@v0.1.1"
Nanobot config
[mcp.confluence]
command = "uvx"
args = ["--from", "git+https://github.com/bonkey/confluence-mini-mcp", "confluence-mini-mcp"]
env = { CONFLUENCE_BASE_URL = "https://company.atlassian.net/wiki", CONFLUENCE_EMAIL = "you@company.com", CONFLUENCE_API_TOKEN = "...", CONFLUENCE_ROOT_PAGE_IDS = "123456,789012" }Tools
| Tool | Description | |------|-------------| | search_pages | Keyword search across cached pages (title 10x weight) | | get_page | Full Markdown content by page ID (Confluence or external) | | list_pages | Index of all cached pages (optional space_key filter) | | refresh_cache | Force re-crawl, bypass TTL |
Crawling
The crawler walks a graph, not just a tree:
- Child pages — standard parent → children traversal
- Linked Confluence pages — any internal link in page content is followed (enables a single "hub page" linking to multiple subtrees)
- External HTTP links — fetched as Markdown (1 level deep, follows redirects only)
In-page directives
Add a [confluence-mcp] block anywhere on a Confluence page to control crawl behaviour for that subtree:
[confluence-mcp]
max_depth=3
follow_links=false
follow_external=true| Directive | Default | Description | |-----------|---------|-------------| | max_depth | (global config) | Override crawl depth from this page down | | follow_links | true | Follow linked Confluence pages in content | | follow_external | true | Fetch external HTTP links in content |
The directive block is stripped from the Markdown output — agents never see it.
Configuration
All settings via env vars or confluence-mini-mcp.toml:
| Env var | Description | Default | |---------|-------------|---------| | CONFLUENCE_BASE_URL | Wiki base URL | required | | CONFLUENCE_EMAIL | Atlassian email | required | | CONFLUENCE_API_TOKEN | API token | required | | CONFLUENCE_ROOT_PAGE_IDS | Comma-separated root page IDs | required | | CONFLUENCE_CACHE_DIR | Cache directory | ~/.cache/confluence-subtree-mcp | | CONFLUENCE_CACHE_TTL_MINUTES | Cache max age | 30 | | CONFLUENCE_MAX_DEPTH | Max crawl depth | 10 | | CONFLUENCE_MAX_PAGES | Max pages to crawl | 500 | | CONFLUENCE_REFRESH_INTERVAL | Background refresh interval (0=off) | 5 | | CONFLUENCE_DRY_RUN | Fake cache mode, no API calls | false |
Development
just dev # run in dry-run mode
just check # format + test
just release # tag + push
