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 attachments
  • read_page: Fetch full page content with automatic HTML-to-Markdown conversion
  • list_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 --http flag 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 FastMCP
• host.py - MCP client for testing
• pyproject.toml - Project metadata and dependencies (uv configuration)
• requirements.txt - Python dependencies (for pip compatibility)
• Dockerfile - Container configuration
• .env.example - Environment variables template
• mcp-config.example.json - MCP Inspector configuration template
• func_req.md - Functional requirements specification
• TESTING.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:

1. Ensure all three tools maintain backward compatibility
2. Add appropriate error handling for new API calls
3. Update documentation for new features
4. Test with both local and Docker deployment

License

[Your License Here]

Resources

• Model Context Protocol Documentation
• Confluence Cloud REST API
• FastMCP Documentation

confluence-mcp-container