awesome-confluence-mcp

# Awesome Confluence MCP - AI Agent Discovery ## Overview This MCP server provides AI agents with token-efficient access to Confluence content through three powerful tools. By converting HTML to Markdown, it reduces token consumption by 60-80%, enabling more efficient knowledge retrieval and analysis. ## Available Tools ### 1. `list_spaces` **Purpose:** Discover available Confluence spaces **When to use:** - User wants to browse available documentation - Need to identify which space contains relevant information - Starting point for Confluence exploration **Parameters:** - `limit` (optional, 1-100): Number of spaces to return **Returns:** JSON with space keys, names, types, and URLs ### 2. `search_pages` **Purpose:** Find pages by title or content **When to use:** - User asks about a specific topic - Need to locate documentation on a subject - Want to find pages in a specific space **Parameters:** - `query` (required): Search term - `space_key` (optional): Limit to specific space - `limit` (optional, 1-50): Number of results **Returns:** JSON with page IDs, titles, spaces, versions, and URLs ### 3. `fetch_page_markdown` **Purpose:** Retrieve page content in token-efficient Markdown format **When to use:** - User needs to read/analyze page content - Want to extract information from documentation - Need to reference specific procedures or policies **Parameters:** - `page_id` (required): Confluence page ID **Returns:** Markdown-formatted content with metadata (title, space, version, URL, labels) ## Integration Guide ### Recommended Workflow 1. **Discovery Phase:** ``` User: "What documentation do we have about authentication?" Agent: Use search_pages(query="authentication") ``` 2. **Retrieval Phase:** ``` Agent: Identify relevant page IDs from search results Agent: Use fetch_page_markdown(page_id="123456") for each relevant page ``` 3. **Analysis Phase:** ``` Agent: Process Markdown content (60-80% fewer tokens than HTML) Agent: Provide answer based on retrieved documentation ``` ### Example Prompts **Browse available spaces:** - "What Confluence spaces are available?" - "Show me all documentation spaces" - "List the knowledge bases" **Search for content:** - "Find pages about API authentication" - "Search for onboarding documentation in the HR space" - "Look for deployment procedures" **Fetch specific pages:** - "Get the content of page 789012" - "Show me the API documentation page" - "Retrieve the onboarding checklist" **Combined workflows:** - "Find and summarize all pages about security policies" - "Search for 'deployment' and show me the most recent page" - "Get all documentation about the authentication system" ## Token Efficiency **Why this matters for AI agents:** Confluence pages in HTML format are extremely verbose. A typical 2,000-word page: - **HTML:** ~2,500 tokens - **Markdown:** ~600 tokens - **Savings:** 76% reduction **Benefits:** - Fit more documentation in context window - Reduce API costs significantly - Faster processing and response times - Better context retention across conversations ## Best Practices ### 1. Use Search Before Fetch Always search first to find relevant pages, then fetch only what's needed: ``` ✅ search_pages → fetch_page_markdown (targeted) ❌ fetch_page_markdown (guessing page IDs) ``` ### 2. Leverage Space Filtering When the user mentions a specific area, use `space_key`: ``` search_pages(query="deployment", space_key="DEVOPS") ``` ### 3. Respect Limits Start with small limits and increase if needed: ``` search_pages(query="api", limit=5) # Start small ``` ### 4. Extract Metadata The Markdown output includes valuable metadata: - **Space:** Context about where the page lives - **Version:** How recently it was updated - **Labels:** Tags for categorization - **URL:** Direct link for users ## Error Handling The tools provide clear error messages: - Missing credentials → "Error: Missing required environment variables" - Invalid page ID → "Error: No content found for page ID" - API errors → "Confluence API error: [status code]" Always check for "Error:" prefix in responses and inform the user appropriately. ## Configuration Requirements This server requires three environment variables: - `CONFLUENCE_URL`: Atlassian instance URL - `CONFLUENCE_EMAIL`: User email for authentication - `CONFLUENCE_API_TOKEN`: API token from Atlassian Users must configure these before the server can function. ## Use Cases ### Documentation Retrieval "Find and summarize our API documentation" → Search for API pages, fetch top results, provide summary ### Policy Lookup "What's our remote work policy?" → Search for "remote work policy", fetch the page, extract key points ### Onboarding Assistance "Show me the onboarding checklist for new developers" → Search in HR/Dev space, fetch onboarding pages, present checklist ### Technical Research "How do we handle authentication in our services?" → Search for "authentication", fetch relevant pages, synthesize answer ### Change Tracking "What's the latest version of the deployment guide?" → Search for deployment guide, fetch page, show version and last update ## Performance Tips 1. **Batch searches** when possible instead of multiple individual fetches 2. **Cache page IDs** for frequently accessed documentation 3. **Use specific queries** to reduce irrelevant results 4. **Leverage space filtering** to narrow search scope ## Security Considerations - All requests use API token authentication - Respects Confluence permissions (users only see what they have access to) - No credentials are stored in the server code - Environment variables keep secrets secure --- **For AI Agents:** This server is your gateway to token-efficient Confluence access. Use it to help users find, retrieve, and analyze documentation while minimizing token costs and maximizing context efficiency.