Confluence MCP Gateway Service

This service, built upon the FastMCP framework, bridges applications to the Confluence REST API, enabling automated management of knowledge assets, including spaces, individual page documents, and complex content lookups.

Core Capabilities

• Space Administration: Functions for enumerating and filtering organizational spaces.
• Document Manipulation: Operations to fetch and update the content body of specific pages.
• Advanced Search: Execution of queries leveraging CQL (Confluence Query Language).
• Hierarchical Traversal: Ability to map out all articles within a designated space key.
• Security Model: Utilizes securely managed API key authentication for all endpoints.

Prerequisites

• Minimum Python version: 3.8 or newer.
• Python package installer (pip).
• Access credentials to an active Confluence installation.
• A provisioned, valid Confluence Personal Access Token (API Token).

Deployment Instructions

Automated Installation (Smithery)

Install the component directly into your Claude Desktop environment using the Smithery CLI:

bash npx -y @smithery/cli install @MahithChigurupati/confluence-mcp-server --client claude

Manual Setup Procedure

1. Source Code Retrieval bash git clone https://github.com/MahithChigurupati/Confluence-MCP-Server.git cd Confluence-MCP-Server

2. Environment Isolation (Best Practice) bash python -m venv venv

For Linux/macOS

source venv/bin/activate

For Windows CMD

.\venv\Scripts\activate

1. Dependency Resolution bash pip install -r requirements.txt

Configuration Step-by-Step

1. Configuration File Staging bash cp .env.example .env

2. Populating Credentials in .env plaintext CONFLUENCE_BASE_URL=https://your-domain.atlassian.net/wiki/rest/api USERNAME=your.login.email@domain.com API_TOKEN=your-secret-token-here

3. Generating the API Token Navigate to Atlassian Security Settings. Select "Create API Token," assign a label (e.g., "MCP Server Connector"). Crucially, copy the token immediately upon generation, as it is non-recoverable.

Operational Guide

Launching the Gateway

Execute the main server script: bash python confluence.py

Exposed Remote Procedures

1. Space Enumeration

python

Retrieves a paginated list of available spaces, optionally filtered

response = await list_spaces( query="development", limit=50,
start=0
)

2. Content Retrieval by ID

python

Fetches the raw markup or storage format of a specific page

response = await get_page_content( page_id="987654",
version=1
)

3. Content Searching

python

Executes a structured search across Confluence content

response = await search_content( query="Q4 roadmap details",
space_key="ENG",
limit=100,
start=0
)

4. Space Content Listing

python

Retrieves all direct descendant pages for a given space key

response = await list_pages_in_space( space_key="PROJECTS",
limit=200,
start=0
)

Client Integration Configurations

Claude Desktop Integration

Add the following structure to your ~/.claude/claude_desktop_config.json file:

{ "mcpServers": { "confluence_connector": { "command": "python executable path", "args": ["/full/path/to/Confluence-MCP-Server/confluence.py"] } } }

Cursor Integration

Configure ~/.cursor/mcp.json:

{ "mcpServers": { "confluence_connector": { "command": "python executable path", "args": ["/full/path/to/Confluence-MCP-Server/confluence.py"] } } }

Tip: Determine your Python path using which python on Unix-like systems or where python on Windows. Append the script path as the final argument.

Exception Handling Map

Encountered HTTP status codes usually indicate:

• 401: Authentication failure (Bad token or credentials).
• 403: Authorization denial (Permissions insufficient).
• 404: The requested Confluence resource identifier does not exist.
• 429: Temporary service interruption due to rate limiting.

Troubleshooting Common Failures

1. Connection Problems
2. Confirm CONFLUENCE_BASE_URL accurately points to the API root.
3. Verify network routing to the Atlassian host.

4. Re-validate the API token's active status.

5. Credential Failures

6. Ensure the configured USERNAME matches the email associated with the token.

7. Check for accidental whitespace or special character corruption in the .env file's token entry.

8. Access Denied

9. The token owner must possess explicit read/write permissions for the targeted spaces/pages.

Support and Licensing

Feature requests or bug reports should be submitted through the repository's dedicated issue tracker.

License: MIT. See the accompanying LICENSE file for legal details.