Skip to main content
Glama
OkYongChoi

Confluence MCP Server

by OkYongChoi
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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

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-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

confluence-mcp-container

Available Tools

3 tools
list_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

ParametersJSON Schema
NameRequiredDescriptionDefault
space_keyYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions the return format ('Dictionary containing list of pages with title and id'), which adds some behavioral context, but fails to disclose critical traits like pagination behavior, rate limits, authentication needs, or whether it's a read-only operation. For a tool with zero annotation coverage, this leaves significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with the core purpose stated first, followed by structured sections for args and returns. Every sentence adds value, though the 'Args:' and 'Returns:' labels could be slightly more integrated for optimal flow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 parameter), no annotations, and the presence of an output schema (which handles return values), the description is reasonably complete. It covers the purpose, parameter semantics, and return format, though it lacks behavioral details like pagination or error handling, preventing a perfect score.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains the 'space_key' parameter's purpose ('The Confluence space key') and provides an example ('e.g., 'TEAM', 'DOCS''), adding meaningful context beyond the bare schema. With only one parameter, this is sufficient to earn a high score, though not a 5 due to lack of deeper semantic details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('List all pages') and resource ('within a specific Confluence workspace'), distinguishing it from siblings like 'read_page' (which reads a single page) and 'search_confluence' (which searches across spaces). The verb+resource combination is precise and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by specifying the required 'space_key' parameter, but does not explicitly state when to use this tool versus alternatives like 'search_confluence'. It provides context (listing pages in a specific space) but lacks explicit guidance on exclusions or comparative use cases with siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
page_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool fetches content, implying a read-only operation, but doesn't clarify aspects like authentication requirements, rate limits, error handling, or whether it accesses public or private pages. The description adds minimal behavioral context beyond the basic action, missing key details for safe and effective use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise and well-structured. It starts with a clear purpose statement, followed by dedicated sections for 'Args' and 'Returns,' each with brief, relevant details. Every sentence earns its place, with no redundant or verbose language, making it easy to scan and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one parameter) and the presence of an output schema (implied by 'Returns' details), the description is moderately complete. It covers the basic action and parameter semantics but lacks usage guidelines and behavioral transparency, which are important for a tool with no annotations. The output information helps, but overall completeness is adequate with noticeable gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description must compensate. It adds meaningful semantics by specifying that 'page_id' is 'The Confluence page ID,' clarifying the parameter's purpose and format. However, it doesn't detail constraints like ID format or examples, leaving some ambiguity. With one parameter and no schema descriptions, this is above baseline but not fully comprehensive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Fetch the full content of a specific page by its ID.' It specifies the verb ('fetch'), resource ('page'), and scope ('by its ID'), making the action unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'list_space_content' or 'search_confluence', which likely serve different purposes (listing vs. searching vs. fetching a specific page).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools or contexts where other tools might be more appropriate, such as using 'search_confluence' when the page ID is unknown or 'list_space_content' for browsing. There's also no information on prerequisites or constraints, leaving usage decisions to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool searches for content and returns a dictionary with results, but it lacks details on behavioral traits such as permissions required, rate limits, pagination, or how search results are ordered/filtered. For a search tool with zero annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with the core purpose stated first in a clear sentence. The additional 'Args' and 'Returns' sections are structured but could be more integrated; they add necessary details without redundancy. A minor deduction for slight structural separation, but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (search functionality), no annotations, and an output schema present (which covers return values), the description is partially complete. It explains the purpose and basic I/O but lacks context on usage guidelines, behavioral details, and parameter nuances. The output schema reduces the need to describe returns, but gaps in other areas make it only adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds minimal semantics beyond the input schema. It defines 'query' as a 'Search query string to find content in Confluence,' which provides basic meaning. However, with 0% schema description coverage and only one parameter, the baseline is high (4 for 0 params), but the description does not fully compensate by explaining query syntax, examples, or constraints (e.g., wildcards, field-specific searches), so it scores slightly below baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Search for pages, blog posts, or attachments in Confluence.' It specifies the verb ('Search') and the resources ('pages, blog posts, or attachments'), making it easy to understand what the tool does. However, it does not explicitly differentiate from sibling tools like 'list_space_content' or 'read_page' (e.g., by noting this is a general search vs. space-specific listing or direct page reading), which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It mentions what it searches for but does not specify contexts (e.g., 'use this for broad queries across all content types' vs. 'use list_space_content for content within a specific space') or exclusions. This lack of comparative information leaves the agent without clear usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count3/5

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.

Completeness2/5

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

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/OkYongChoi/confluence-mcp-container'

If you have feedback or need assistance with the MCP directory API, please join our Discord server