Awesome Confluence

You can deploy an MCP server that securely fetches Confluence content, converts pages to token-efficient Markdown, and exposes convenient commands for listing spaces, searching pages, and fetching content as Markdown for your AI agents. This setup helps you reduce token usage while maintaining formatting and structure for rapid analysis and research.

How to use

To use the Confluence MCP server, start the local server from your project workspace and connect your MCP client to it. The server provides three core capabilities: list spaces, search pages by title or content, and fetch a page in Markdown format. You will authenticate with Atlassian API tokens and supply your Confluence instance URL, email, and token in environment variables.

Typical usage workflow: list spaces to discover available namespaces, search for pages related to your topic, and fetch the most relevant pages as Markdown for analysis. All results are returned in a concise, token-efficient format suitable for downstream AI agents or code assistants.

How to install

Prerequisites: you need Python installed and access to a terminal. You will also clone the MCP server repository and install the Python package in editable mode.

# Clone the repository
git clone https://github.com/mazhar480/awesome-confluence-mcp.git
cd awesome-confluence-mcp

# Install with pip
pip install -e .

MCP command to start the server

The server runs as a Python module. You use the following command to start it from your project directory, ensuring your environment is configured with the Confluence URL, email, and API token.

python -m server

Environment configuration

Create and configure a local environment file to provide your Confluence connection details. The example below shows how to set the Confluence URL, email, and API token.

# Copy the example file
cp .env.example .env

# Edit .env with your credentials
CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_EMAIL=your.email@example.com
CONFLUENCE_API_TOKEN=your_api_token_here

Connecting a client to the MCP server

Two explicit local startup configurations are shown to run the server from the client side. Use either configuration in your MCP client depending on your editor or environment.

# Claude Desktop client configuration snippet
{
  "mcpServers": {
    "confluence": {
      "command": "python",
      "args": ["-m", "server"],
      "cwd": "/path/to/awesome-confluence-mcp",
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_EMAIL": "your.email@example.com",
        "CONFLUENCE_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

# Cline (VS Code Extension) configuration snippet
{
  "confluence": {
    "command": "python",
    "args": ["-m", "server"],
    "cwd": "/path/to/awesome-confluence-mcp"
  }
}

Notes on credentials and security

Keep your tokens secret. Never commit the .env file to version control. Use API tokens with the minimum required scope and rotate them periodically.

Security best practices

• Never commit your .env file to version control. - Use API tokens instead of passwords. - Rotate tokens regularly. - Limit token scope to only what is needed. - Store tokens securely in environment variables.

Testing with MCP Inspector

You can test all MCP tools without a full client using the built-in MCP Inspector. It launches a web interface to interact with the server, validate credentials, and try different parameter sets.

npx @modelcontextprotocol/inspector python server.py

Notes on usage patterns

Common tasks include listing spaces to discover your accessible namespaces, performing targeted searches for pages relevant to a topic, and fetching the content you want analyzed as Markdown to minimize token usage while preserving structure.

Available tools

list_spaces

Lists all Confluence spaces you have access to. Returns a total count and basic space details.

search_pages

Searches pages by title or content with optional space filtering and limit on results.

fetch_page_markdown

Fetches a Confluence page by ID and returns the content converted to Markdown.