Confluence MCP Server
Enables interaction with the Atlassian ecosystem by connecting to Confluence Cloud or Server instances for documentation and workspace management.
Provides tools to search for pages, blog posts, and attachments, fetch full page content with HTML-to-Markdown conversion, and list all pages within a specific workspace.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Confluence MCP Server search for the project onboarding documentation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: awesome-confluence-mcp
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-test2. Configure Credentials
Create a .env file from the example:
cp .env.example .envEdit .env with your Confluence credentials:
CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_USERNAME=your-email@example.com
CONFLUENCE_API_TOKEN=your-api-token-here3. 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/activateUsing pip
pip install -r requirements.txt4. 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 credentialsThe 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.jsonThis 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-mcpConnect 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 HTTPBenefits: 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 listRequirements 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]
Resources
confluence-mcp-container
Available Tools
3 toolslist_space_contentA
List all pages within a specific Confluence workspace.
Args: space_key: The Confluence space key (e.g., 'TEAM', 'DOCS')
Returns: Dictionary containing list of pages with title and id
Inputs: space_key (required). Returns: object
read_pageB
Fetch the full content of a specific page by its ID.
Args: page_id: The Confluence page ID
Returns: Dictionary containing page title and content in Markdown format
Inputs: page_id (required). Returns: object
search_confluenceC
Search for pages, blog posts, or attachments in Confluence.
Args: query: Search query string to find content in Confluence
Returns: Dictionary containing search results with title, type, and id
Inputs: query (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: list_space_content retrieves all pages in a workspace, read_page fetches specific page content, and search_confluence performs general searches. There is no overlap in functionality, making tool selection unambiguous.
All tools follow a consistent verb_noun pattern (list_space_content, read_page, search_confluence) with clear, descriptive names. The naming convention is uniform and predictable throughout the set.
With only 3 tools, the set feels thin for a Confluence server, lacking essential operations like create, update, or delete pages. While the tools cover basic read/search functionality, the scope is incomplete for typical content management workflows.
The tool surface is significantly incomplete for a Confluence domain. It only supports listing, reading, and searching content, with no ability to create, update, or delete pages, spaces, or attachments. This will cause agent failures in common content management tasks.
Maintenance
Related MCP Connectors
Convert PDF, Word, Excel, PowerPoint, e-mails and web pages to clean Markdown for LLMs.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
Web pages and PDFs to clean, LLM-ready Markdown with token counts, small crawls and RAG chunks.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables AI assistants like Claude to access and search Atlassian Confluence content, allowing integration with your organization's knowledge base.511,118 npm63ISC
- AlicenseBqualityDmaintenance🚀 Token-efficient MCP server for Confluence. Reduces LLM costs by 76% via Markdown conversion. Supports listing, searching, and fetching pages.33MIT
- FlicenseAqualityDmaintenanceEnables reading and analyzing Confluence documentation content through the Confluence REST API. Supports extracting and converting text, tables, code blocks, and images from Confluence pages for Q\&A and analysis.6-
- AlicenseBqualityDmaintenanceEnables querying and interacting with a Markdown wiki generated from Confluence pages, with search and MCP server for LLM access.104MIT