Confluence Access Gateway

This FastMCP implementation acts as a dedicated intermediary for consuming the Confluence REST Endpoints, facilitating automated management of knowledge base assets, including spaces, individual documents, and full-text querying capabilities.

Core Capabilities

• Space Administration: Catalog and filter existing Confluence site containers (spaces).
• Document Manipulation: Fetch and update specific page artifacts.
• Information Retrieval: Execute sophisticated queries using CQL (Confluence Query Language).
• Structure Traversal: Map out the document hierarchy within designated spaces.
• Security Model: Secure transactions rely exclusively on API key authentication.

Prerequisites

• Runtime Environment: Python version 3.8 or newer.
• Dependency Manager: pip for package resolution.
• Target System: A provisioned Confluence host accessible via HTTP/S.
• Credentials: A valid, non-expired Confluence API access credential.

Deployment Procedures

Installation via Smithery (Automated)

For rapid deployment within Claude Desktop environments using Smithery:

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

Manual Setup Guide

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

2. Environment Isolation (Best Practice) bash python -m venv env_c source env_c/bin/activate # Unix-like systems # or .\env_c\Scripts\activate # Windows systems

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

Operational Setup

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

2. Parameterization of Environment Variables plaintext CONFLUENCE_BASE_URL=https://your-organization.atlassian.net/wiki/rest/api USERNAME=your.registered.email@domain.com API_TOKEN=your-generated-secret-token

3. API Token Generation Workflow

4. Navigate to Atlassian Security Settings
5. Select "Create new token".
6. Assign a descriptive label (e.g., "MCP Gateway Access").
7. Crucially, copy the generated string immediately, as retrieval is a one-time action.

Execution Instructions

Launching the Gateway

bash python confluence.py

Exposed Method Signatures

1. Retrieve Space Index

python results = await list_spaces( query="development", # Optional: Substring match for space names limit=25, # Optional: Max records per response start=0 # Optional: Offset for pagination )

2. Fetch Page Body

python content_data = await get_page_content( page_id="987654", # Mandatory: Unique identifier for the document version=1 # Optional: Retrieve a specific historical revision )

3. Execute Content Search

python search_payload = await search_content( query="Q4 roadmap", # Mandatory: The search directive space_key="TECH", # Optional: Scope the search to a specific space key limit=100, # Optional: Result cap start=0 # Optional: Paging index )

4. List Documents within a Space

python page_list = await list_pages_in_space( space_key="HR_DOCS", # Mandatory: Target space identifier limit=500, # Optional: Upper bound on returned items start=0 # Optional: Starting offset )

Client Integration Guides

Claude Desktop Configuration Snippet

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

Storage Location: ~/.claude/claude_desktop_config.json (Unix/Mac) or %USERPROFILE%\.claude\config.json (Windows)

Cursor Configuration Snippet

{ "mcpServers": { "confluence": { "command": "python", "args": ["/path/to/repository/confluence.py"] } } }

Use which python or where python to resolve the executable path. Utilize pwd within the checked-out directory to confirm the absolute path to confluence.py.

Troubleshooting Common Failures

Error Codes Reference:

• 401: Credential failure (token or user ID invalid).
• 403: Authorization denied (user lacks necessary permissions).
• 404: The requested resource identifier does not exist.
• 429: Transaction volume exceeds the server's allowed throughput.

Resolution Steps

1. Network Connectivity Issues
2. Verify that the CONFLUENCE_BASE_URL syntax is precise.
3. Confirm firewall rules permit outbound connections.

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

5. Credential Malfunction

6. Cross-reference the USERNAME with the Atlassian login email.

7. Ensure the API_TOKEN was copied without extraneous whitespace.

8. Access Rights Problems

9. Confirm the associated user account possesses read/write permissions to the target space/page.

Support Structure

For defect reporting or feature solicitation, please file an official report via the project's issue tracking system.

Licensing

This software is distributed under the MIT License. Refer to the included LICENSE file for comprehensive terms.