Confluence MCP Server

A Model Context Protocol (MCP) server that provides search capabilities for Atlassian Confluence. This server enables AI assistants and other MCP clients to search and retrieve information from your Confluence instance.

Features

• Confluence Search: Search for pages using Confluence Query Language (CQL)
• HTTP Transport: Uses FastMCP's HTTP transport for easy integration
• Cloud Support: Works with Confluence Cloud instances
• Simple Setup: Easy configuration via environment variables
• Configurable Results: Control how many search results are returned

Prerequisites

• Python 3.10 or higher
• A Confluence Cloud instance
• Confluence API credentials (email + API token)

Setup

1. Install Dependencies

This project uses uv for dependency management:

uv sync

2. Configure Credentials

Create a .env file in the project root:

cp .env.example .env

Edit the .env file and add your Confluence credentials:

CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_USERNAME=your-email@example.com
CONFLUENCE_API_TOKEN=your-api-token
# Optional: Maximum number of search results to return (default: 10)
CONFLUENCE_MAX_RESULTS=10
# Optional: Network configuration for the MCP HTTP transport
# Port the server listens on (default: 3000)
MCP_PORT=3000
# Base path the MCP server is mounted on (default: /mcp)
MCP_PATH=/mcp
# Optional: Instructions for the MCP server. If omitted a default will be used.
MCP_INSTRUCTIONS=Search Confluence for pages matching query terms.

Environment Variables

Variable	Required	Default	Description
CONFLUENCE_URL	Yes	-	Your Confluence instance URL
CONFLUENCE_USERNAME	Yes	-	Your Confluence email address
CONFLUENCE_API_TOKEN	Yes	-	Your Confluence API token
CONFLUENCE_MAX_RESULTS	No	10	Maximum number of search results to return (1-100)
MCP_PORT	No	3000	Port the MCP HTTP transport listens on
MCP_PATH	No	/mcp	Base path the MCP server is mounted on (must start with /)
MCP_INSTRUCTIONS	No	Default message	Instructions passed to the MCP server describing tool behavior and result formatting

How to get an API Token

1. Log in to Atlassian Account Settings
2. Click "Create API token"
3. Give it a label (e.g., "MCP Server")
4. Copy the generated token to your .env file

Usage

Start the Server

Run the server with default settings (port 3000, path /mcp):

uv run confluence-mcp-server

Or run directly:

uv run python main.py

The server will start on http://0.0.0.0:3000/mcp You can customize the host/port/path via environment variables. For example, to run on port 8080 and mount at /api/mcp:

MCP_PORT=8080 MCP_PATH=/api/mcp uv run python main.py

Then the server will be available at http://0.0.0.0:8080/api/mcp

Available Tools

search_confluence

Search Confluence for pages matching a query term.

Parameters:

• query (string): The search term to find in Confluence pages

Example:

{
  "query": "project documentation"
}

Returns: A formatted list of matching pages (up to CONFLUENCE_MAX_RESULTS) with:

• Page title
• Space key
• Page type
• Direct URL to the page

Integration with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "confluence": {
      "command": "uv",
      "args": ["run", "confluence-mcp-server"],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USERNAME": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_MAX_RESULTS": "50"
      }
    }
  }
}

Other MCP Clients

Connect to the HTTP endpoint at http://localhost:3000/mcp

Development

Testing

You can test the server using the MCP Inspector or any HTTP client:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_confluence",
      "arguments": {
        "query": "test"
      }
    }
  }'

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.