Confluence MCP Server
A Model Context Protocol (MCP) server for Atlassian Confluence. This server provides tools to search, read, create, and update Confluence pages, with built-in access controls for safe AI interactions.
Features
- Search: Find pages using Confluence Query Language (CQL), automatically filtered by allowed spaces and specific page IDs.
- Read: Retrieve page content as both plain text (for reasoning) and storage format (HTML, for editing).
- Create: Create new pages in whitelisted spaces and under specific parent pages. Automatically applies the
ai-managedlabel. - Update: Safely update pages. Enforces that pages must have the
ai-managedorai-generatedlabel to be modifiable. - Smart Merge: Helper tool to fetch context for merging updates into existing pages.
- Get Children: Retrieve direct child pages of a specific page. Useful for navigating the hierarchy when search is unreliable.
- Configurable Access Control: Permissions are defined in
config.json, not hardcoded.
Installation
Option 1: Install via pip (Recommended)
You can install the package directly if you have it locally or from a git repo:```bash
pip install .
### Option 2: Install via uv (Fastest)
If you use uv, you can install dependencies and run the project efficiently.```bash
uv pip install .
Option 3: Run from source
- Clone the repository.
- Install dependencies:
bash pip install -r requirements.txt
Note:requirements.txtis provided for convenience, butpyproject.tomlis the source of truth.
Configuration
1. Environment Variables
The server requires the following environment variables for authentication:
CONFLUENCE_BASE_URL: Base URL of your Confluence instance (e.g.,https://your-domain.atlassian.net/wiki).CONFLUENCE_EMAIL: Your Atlassian account email.CONFLUENCE_API_TOKEN: Your Atlassian API token.
For the Agent, you also need LLM keys:
* OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY.
2. Access Control (config.json)
Create a config.json file in the directory where you will run the server. You can copy config.example.json as a starting point.```json
{
"allowed_spaces": ["AR", "ENG", "KB"],
"allowed_parents": {
"AR": ["2424881", "2490466"],
"ENG": ["223344"],
"KB": ["998877"]
}
}
* **allowed_spaces**: List of space keys the AI can access.
* **allowed_parents**: Dictionary mapping space keys to a list of Page IDs.
* **For Creation**: New pages can *only* be created as children of these IDs.
* **For Search**: Search results are restricted to *only* these IDs.
The server looks for `config.json` in the following order:
1. Path specified by `CONFLUENCE_MCP_CONFIG` environment variable.
2. Current working directory.
3. Package directory (fallback).
## Usage
### Running the MCP Server
**Standard:**```bash
confluence-mcp
With uv:```bash
uv run confluence-mcp
### Running the Conversational Agent
This project includes a **Chainlit** agent that connects to the MCP server.
**Using the launcher script (recommended):**```bash
./start_agent.sh
This automatically starts the agent with remote access enabled.
Manual start (local access only):```bash
chainlit run src/confluence_mcp/agent/app.py -w
**Manual start with remote access:**```bash
chainlit run src/confluence_mcp/agent/app.py -w --host 0.0.0.0 --port 8000
With uv:```bash
uv run chainlit run src/confluence_mcp/agent/app.py -w --host 0.0.0.0 --port 8000
**Access URLs:**
- Local: `http://localhost:8000`
- Remote: `http://:8000` (e.g., `http://192.168.0.179:8000`)
**Features:**
- 🎤 Voice input (using Google Gemini for transcription)
- 🔍 Smart search with ancestor filtering
- 📝 Create and update Confluence pages
- 💬 Natural language interface
- 🎯 Starter prompts for common tasks
### Connecting to an MCP Client
You can use this server with any MCP-compatible client (Claude Desktop, Cursor, etc.).
#### Claude Desktop (`claude_desktop_config.json`)```json
{
"mcpServers": {
"confluence": {
"command": "uv",
"args": ["run", "confluence-mcp"],
"env": {
"CONFLUENCE_BASE_URL": "https://your-domain.atlassian.net/wiki",
"CONFLUENCE_EMAIL": "user@example.com",
"CONFLUENCE_API_TOKEN": "your-api-token"
}
}
}
}
Cursor
- Go to Settings > MCP.
- Click Add New MCP Server.
- Name:
confluence(or any name you prefer). - Type:
command. - Command:
uv run confluence-mcp(ensure you are in the project directory or provide the full path touvand the project). - Environment Variables: Add your
CONFLUENCE_...keys here.
License
MIT
