Confluence MCP Server

A Model Context Protocol (MCP) server for integrating Confluence with AI applications like Claude.

Overview

This MCP server provides tools to interact with Confluence spaces and pages, enabling AI applications to:

• List and search Confluence spaces
• Browse pages and page content
• Search across Confluence
• Get Confluence instance information

Features

The server exposes the following tools:

• list_spaces: List all Confluence spaces
• get_space_details: Get detailed information about a specific space
• list_pages: List pages in a specific space
• get_page_content: Get the content of a page by title
• search_pages: Search for pages using CQL (Confluence Query Language)
• get_confluence_info: Get information about the Confluence instance

Installation

Prerequisites

• Python 3.10 or higher
• uv (recommended) or pip for package management

Setup

1. Clone or create the project directory
2. Install dependencies using uv:

\\bash uv sync \\

Or with pip:

\\bash pip install -r requirements.txt \\

Configuration

1. Copy the example configuration:

\\bash cp .env.example .env \\

2. Edit .env and add your Confluence credentials:

For Confluence Cloud:

\\env CONFLUENCE_URL=https://your-domain.atlassian.net CONFLUENCE_USERNAME=your-email@example.com CONFLUENCE_TOKEN=your-api-token \\

Get your API token from: https://id.atlassian.com/manage-profile/security/api-tokens

For Confluence Server/Data Center:

\\env CONFLUENCE_URL=https://confluence.company.com CONFLUENCE_USERNAME=your-username CONFLUENCE_PASSWORD=your-password \\

Running the Server

With uv:

\\bash uv run confluence_server.py \\

With Python directly:

\\bash python confluence_server.py \\

With MCP Inspector (for testing):

\\bash

Terminal 1: Start the server

uv run confluence_server.py

Terminal 2: Run the inspector

npx -y @modelcontextprotocol/inspector \\

Then connect to http://localhost:8000/mcp in the inspector.

Integration with Claude Desktop

macOS/Linux:

1. Edit your Claude Desktop config:

\\bash code ~/Library/Application Support/Claude/claude_desktop_config.json \\

2. Add the server configuration:

\\json { "mcpServers": { "confluence": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/python-mcp-server", "run", "confluence_server.py" ] } } } \\

3. Restart Claude Desktop

Windows:

1. Edit your Claude Desktop config:

\
code %APPDATA%\Claude\claude_desktop_config.json \\

2. Add the server configuration with forward slashes:

\\json { "mcpServers": { "confluence": { "command": "uv", "args": [ "--directory", "C:/Dev/Confluence MCP Hackathon/python-mcp-server", "run", "confluence_server.py" ] } } } \\

3. Restart Claude Desktop

Example Usage

Once integrated with Claude Desktop, you can ask:

• "What spaces do we have in Confluence?"
• "Show me the pages in the Engineering space"
• "Search for documentation about API"
• "Get the content of the Getting Started page in our main space"
• "What Confluence version are we running?"

Architecture

The server uses:

• mcp[cli]: The official Python MCP SDK with FastMCP
• atlassian-python-api: Python library for Confluence API interaction
• FastMCP: Simplified MCP server framework with automatic tool discovery

Tool Details

list_spaces(limit: int = 25)

Lists Confluence spaces with pagination support.

get_space_details(space_key: str)

Returns detailed information about a space including name, key, type, and description.

list_pages(space_key: str, limit: int = 10)

Lists pages in a specific space with pagination.

get_page_content(space_key: str, page_title: str)

Retrieves the content of a specific page by its title.

search_pages(query: str, limit: int = 10)

Searches for pages using CQL (Confluence Query Language). Example queries:

• \ ext ~ "keyword"\
• \space = KEY AND type = page\
• \created <= -1d\

get_confluence_info()

Returns information about the Confluence instance including version and URL.

Error Handling

The server handles common errors gracefully:

• Missing credentials
• Connection failures
• Invalid space keys or page titles
• API rate limiting

All errors are returned as readable messages to the AI client.

Troubleshooting

Connection Issues

1. Verify CONFLUENCE_URL is correct
2. Check credentials are valid
3. Ensure your Confluence instance is accessible from your machine
4. For Cloud, verify your API token hasn't expired

Tool Not Showing Up in Claude

1. Restart Claude Desktop
2. Check the logs in Claude Server > Server Logs
3. Verify the .env file contains valid credentials

Security

Important: Never commit your .env file to version control. The .env.example file shows the required variables without sensitive data.

For production deployments:

• Use environment variables or secure credential management
• Consider using OAuth2 authentication
• Restrict API token permissions to minimum required

Development

To extend the server with additional Confluence functionality:

1. Edit confluence_server.py
2. Add new tools using the @mcp.tool() decorator
3. Test with the MCP Inspector
4. Restart Claude Desktop to reload changes

References

• MCP Documentation
• Confluence Python API
• Confluence REST API
• CQL (Confluence Query Language)

License

MIT