Confluence MCP Server
A Model Context Protocol (MCP) server that bridges Confluence Wiki with Large Language Models, enabling LLMs to search, read, and explore Confluence content seamlessly.
Features
- MCP Protocol Compliance: Implements the official Model Context Protocol with stdio communication
- Three Core Tools:
search_confluence: Search for pages, blog posts, and attachmentsread_page: Fetch full page content with automatic HTML-to-Markdown conversionlist_space_content: List all pages within a Confluence workspace
- Smart Content Conversion: Automatically converts Confluence HTML to clean Markdown for optimal LLM context usage
- Robust Error Handling: Gracefully handles authentication (401) and not found (404) errors
- Docker Support: Optional containerization for easy deployment
Prerequisites
- Python 3.11 or higher
- uv (recommended) or pip
- Confluence Cloud or Server instance
- Confluence API token (generate from your Atlassian account settings)
- Docker (optional, for containerized deployment)
Quick Start
1. Clone and Setup
git clone <repository-url>
cd conflience-mcp-test
2. Configure Credentials
Create a .env file from the example:
cp .env.example .env
Edit .env with your Confluence credentials:
CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_USERNAME=your-email@example.com
CONFLUENCE_API_TOKEN=your-api-token-here
3. Install Dependencies
Using uv (recommended)
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Sync dependencies and create virtual environment
uv sync
# Activate the virtual environment
source .venv/bin/activate
Using pip
pip install -r requirements.txt
4. Test the Server
Option A: Using the built-in host client
Run the host client to test the MCP server:
# If using uv, prefix commands with 'uv run' or activate the venv first
uv run python host.py search_confluence '{"query": "project documentation"}'
# Or with activated venv
python host.py search_confluence '{"query": "project documentation"}'
python host.py read_page '{"page_id": "123456"}'
python host.py list_space_content '{"space_key": "TEAM"}'
Option B: Using MCP Inspector (Recommended for Development)
The MCP Inspector is the official testing tool for MCP servers.
Install MCP Inspector:
# TypeScript or Javascript
npx @modelcontextprotocol/inspector node path/to/server/index.js args...
#Python
npx @modelcontextprotocol/inspector \
uv \
--directory path/to/server \
run \
package-name \
args...
Configure the server: The Inspector runs directly through npx without requiring installation:
# Copy the example config
cp mcp-config.example.json mcp-config.json
# Edit mcp-config.json with your Confluence credentials
The config should look like:
{
"mcpServers": {
"confluence": {
"command": "uv",
"args": ["run", "python", "server.py"],
"env": {
"CONFLUENCE_URL": "https://your-domain.atlassian.net",
"CONFLUENCE_USERNAME": "your-email@example.com",
"CONFLUENCE_API_TOKEN": "your-api-token"
}
}
}
}
Launch the Inspector:
mcp-inspector mcp-config.json
This will open a web interface at http://localhost:5173 where you can:
- View all available tools
- Test each tool with custom inputs
- See real-time request/response data
- Debug tool execution
Note: You can also use environment variables from .env by modifying the config to load from the file.
For a comprehensive testing guide including troubleshooting and advanced usage, see TESTING.md.
Docker Deployment
The Docker container runs the MCP server with HTTP/SSE transport (Server-Sent Events), making it accessible over the network.
Build the Image
docker build -t confluence-mcp .
Run the Container
# Run with environment file
docker run --rm -p 8000:8000 --env-file .env confluence-mcp
# Or pass environment variables directly
docker run --rm -p 8000:8000 \
-e CONFLUENCE_URL="https://your-domain.atlassian.net" \
-e CONFLUENCE_USERNAME="your-email@example.com" \
-e CONFLUENCE_API_TOKEN="your-token" \
confluence-mcp
Connect to the Docker Container
Once the container is running, use the host client with the --http flag:
# Test from host machine
python host.py --http http://localhost:8000 search_confluence '{"query": "test"}'
python host.py --http http://localhost:8000 read_page '{"page_id": "123456"}'
# Test from Docker container
python host.py --http http://localhost:8000/sse list_space_content '{"space_key": "TEAM"}'
# Automatically uses "my-server" if it's the only one
npx @modelcontextprotocol/inspector --config mcp-config.json --server confluence-sse
Architecture:
- Server Transport: HTTP/SSE (Server-Sent Events over port 8000)
- Client Connection: Uses
--httpflag to connect via HTTP - Benefits: Can be accessed remotely, scales horizontally, works with load balancers
Architecture
This project implements the Model Context Protocol (MCP), which allows LLMs to interact with external tools and data sources. The server supports two transport modes:
Local Mode (stdio)
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ LLM Client │◄───────►│ MCP Server │◄───────►│ Confluence │
│ (host.py) │ stdio │ (server.py) │ API │ Wiki │
└─────────────────┘ └──────────────────┘ └─────────────────┘
Docker Mode (HTTP/SSE)
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ LLM Client │◄───────►│ MCP Server │◄───────►│ Confluence │
│ (host.py) │HTTP/SSE │ (Docker) │ API │ Wiki │
│ --http flag │ :8000 │ (server.py) │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
Transport Options:
- stdio: For local development and testing
- HTTP/SSE: For containerized deployment, remote access, and production use
API Tools
search_confluence
Search for content across your Confluence instance.
Input:
{
"query": "search terms"
}
Output:
{
"results": [
{
"title": "Page Title",
"type": "page",
"id": "123456"
}
]
}
read_page
Fetch the full content of a Confluence page, converted to Markdown.
Input:
{
"page_id": "123456"
}
Output:
{
"title": "Page Title",
"content": "# Markdown content here...",
"page_id": "123456"
}
list_space_content
List all pages within a specific Confluence space.
Input:
{
"space_key": "TEAM"
}
Output:
{
"space_key": "TEAM",
"pages": [
{
"title": "Page Title",
"id": "123456"
}
],
"total": 42
}
Development
Project Structure
server.py- MCP server implementation using FastMCPhost.py- MCP client for testingpyproject.toml- Project metadata and dependencies (uv configuration)requirements.txt- Python dependencies (for pip compatibility)Dockerfile- Container configuration.env.example- Environment variables templatemcp-config.example.json- MCP Inspector configuration templatefunc_req.md- Functional requirements specificationTESTING.md- Comprehensive testing guide with troubleshooting
Common uv Commands
# Install dependencies
uv sync
# Run server locally (stdio mode)
uv run python server.py
# Run server with HTTP/SSE mode
uv run python server.py --transport sse --host 0.0.0.0 --port 8000
# Run client (stdio mode)
uv run python host.py search_confluence '{"query": "test"}'
# Run client (HTTP mode)
uv run python host.py --http http://localhost:8000 search_confluence '{"query": "test"}'
# Add a new dependency
uv add package-name
# Remove a dependency
uv remove package-name
# Update all dependencies
uv sync --upgrade
# Show installed packages
uv pip list
Requirements Alignment
This implementation follows the requirements specified in func_req.md:
- ✅ REQ-01: Confluence API integration with search, read, and list tools
- ✅ REQ-01: HTML to Markdown conversion for LLM context efficiency
- ✅ REQ-01: Error handling for 401 and 404 responses
- ✅ REQ-02: Docker containerization with stdio communication
- ✅ REQ-02: Environment-based configuration
- ✅ REQ-03: Simple MCP host client with CLI interface
Contributing
This project follows PEP 8 coding conventions. When contributing:
- Ensure all three tools maintain backward compatibility
- Add appropriate error handling for new API calls
- Update documentation for new features
- Test with both local and Docker deployment
License
[Your License Here]