MCP Atlassian Confluence Server

A Model Context Protocol (MCP) server for Atlassian Confluence integration. This project allows AI assistants like Claude Desktop and Cursor AI to access and interact with Atlassian Confluence content through the Model Context Protocol.

Note: This project is forked from boilerplate-mcp-server, a template for building MCP servers. It maintains compatibility with the boilerplate while adding Confluence-specific functionality.

Core Features

This MCP server provides the following capabilities:

Atlassian Confluence Integration

• Spaces Management:

  • list-spaces: List all available Confluence spaces with their IDs, keys, types, and URLs (with filtering options)
  • get-space: Get detailed information about a specific Confluence space by ID, including labels and other metadata

• Pages Management:

  • list-pages: List Confluence pages with filtering options by space ID, status, and more
  • get-page: Get detailed information about a specific Confluence page by ID, including content and metadata

• Search Functionality:

  • search: Search Confluence content using Confluence Query Language (CQL)
  • Intelligent handling of CQL syntax, including automatic quoting of reserved keywords
  • Comprehensive search results with content details and pagination information

• Pagination Support:

  • Cursor-based pagination for spaces, pages listings, and search results
  • Seamless navigation through large result sets
  • Clear pagination information in the output with instructions for retrieving the next page
  • Support in both CLI commands and MCP tools

Configuration Options for End Users

Before setting up with Claude Desktop or Cursor AI, you'll need to configure your Atlassian credentials. There are two recommended options for end users:

Option 1: Direct Configuration in Claude/Cursor

Pass your Atlassian credentials directly in the Claude Desktop config or Cursor AI command:

{
  "mcpServers": {
    "aashari/mcp-atlassian-confluence": {
      "command": "npx",
      "args": ["-y", "DEBUG=true", "ATLASSIAN_SITE_NAME=your_site_name", "ATLASSIAN_USER_EMAIL=your_email", "ATLASSIAN_API_TOKEN=your_token", "aashari/mcp-atlassian-confluence"]
    }
  }
}

Option 2: Global Configuration File (Recommended)

1. Create a global configuration file at $HOME/.mcp/configs.json:

{
  "@aashari/mcp-atlassian-confluence": {
    "environments": {
      "DEBUG": "true",
      "ATLASSIAN_SITE_NAME": "example",
      "ATLASSIAN_USER_EMAIL": "my.username@example.com",
      "ATLASSIAN_API_TOKEN": "your-atlassian-api-token"
    }
  }
}

2. Then use a simplified configuration in Claude Desktop or Cursor AI:

{
  "mcpServers": {
    "aashari/mcp-atlassian-confluence": {
      "command": "npx",
      "args": ["-y", "aashari/mcp-atlassian-confluence"]
    }
  }
}

This approach keeps your credentials in one secure location and simplifies your AI assistant configuration.

Required Configuration

• ATLASSIAN_SITE_NAME: Your Atlassian site name (e.g., for https://example.atlassian.net, use example).
• ATLASSIAN_USER_EMAIL: Email address associated with your Atlassian account.
• ATLASSIAN_API_TOKEN: API token for Atlassian API access (create at Atlassian API tokens).

Optional Configuration

• DEBUG: Set to true to enable debug logging.

Setting Up with Claude Desktop

To use this MCP server with Claude Desktop:

1. Open Claude Desktop Settings:

   • Launch Claude Desktop
   • Click on the settings icon (gear) in the top-right corner

   

2. Edit MCP Configuration:

   • Click on "Edit Config" button
   • This will open File Explorer/Finder with the claude_desktop_config.json file

3. Update Configuration File:

   • Add one of the configuration options from above to the file
   • Save the file

   Example with global configuration file already set up:

   {
     "mcpServers": {
       "aashari/mcp-atlassian-confluence": {
         "command": "npx",
         "args": ["-y", "aashari/mcp-atlassian-confluence"]
       }
     }
   }
   

4. Restart Claude Desktop:

   • Close and reopen Claude Desktop to apply the changes

   

5. Verify Tool Availability:

   • On the Claude home page, look for the hammer icon on the right side
   • Click it to see available tools
   • Ensure the tools are listed

   

6. Test the Tool:

   • Try asking Claude to use one of the available tools
   • For example: "List all Confluence spaces" or "Get details about Confluence space with ID 123456"
   • Claude will use the MCP tool to fetch and display the requested information

Setting Up with Cursor AI

To use this MCP server with Cursor AI:

1. Open Cursor Settings:

   • Launch Cursor
   • Press CMD + SHIFT + P (or CTRL + SHIFT + P on Windows)
   • Type "settings" and select "Cursor Settings"
   • On the sidebar, select "MCP"

   

2. Add New MCP Server:

   • Click "+ Add new MCP server"
   • A configuration form will appear

   

3. Configure MCP Server:

   • Name: Enter aashari/mcp-atlassian-confluence
   • Type: Select command from the dropdown
   • Command: Choose one of the following based on your configuration approach:

   If using global configuration file (recommended):

   npx -y aashari/mcp-atlassian-confluence
   

   If passing credentials directly:

   DEBUG=true ATLASSIAN_SITE_NAME=your_site_name ATLASSIAN_USER_EMAIL=your_email ATLASSIAN_API_TOKEN=your_token npx -y aashari/mcp-atlassian-confluence
   

   • Click "Add"

4. Verify Server Configuration:

   • The server should now be listed with a green indicator
   • You should see the available tools listed under the server

   

5. Test the Tool:

   • In the chat sidebar, ensure Agent mode is active
   • Try asking Cursor AI to use one of the available tools
   • For example: "List all Confluence spaces" or "Get details about Confluence space with ID 123456"
   • Cursor AI will use the MCP tool to fetch and display the requested information

Using as a CLI Tool

The package can also be used as a command-line tool for human interaction:

• Get help and available commands:

  npx -y aashari/mcp-atlassian-confluence --help
  

  Example output:

  Usage: @aashari/mcp-atlassian-confluence [options] [command]
  
  A Model Context Protocol (MCP) server for Atlassian Confluence integration
  
  Options:
    -V, --version               output the version number
    -h, --help                  display help for command
  
  Commands:
    list-spaces [options]       List Confluence spaces with optional filtering
    get-space <spaceId>         Get detailed information about a specific Confluence space
    list-pages [options]        List Confluence pages with optional filtering
    get-page <pageId>           Get detailed information about a specific Confluence page
    search [options] <cql>      Search Confluence content using Confluence Query Language (CQL)
    help [command]              display help for command
  

Spaces Commands

• List Confluence spaces:

  npx -y aashari/mcp-atlassian-confluence list-spaces
  

  With filtering options:

  npx -y aashari/mcp-atlassian-confluence list-spaces --type personal --limit 5
  

  With pagination:

  # Get the first page with 10 results
  npx -y aashari/mcp-atlassian-confluence list-spaces --limit 10
  
  # Get the next page using the cursor from the previous response
  npx -y aashari/mcp-atlassian-confluence list-spaces --limit 10 --cursor "eyJpZCI6MTY3MTE2ODMsInNwYWNlU29ydE9yZGVyIjp7ImZpZWxkIjoiSUQiLCJkaXJlY3Rpb24iOiJBU0NFTkRJTkcifSwic3BhY2VTb3J0T3JkZXJWYWx1ZSI6MTY3MTE2ODN9"
  

  Example output:

  # Confluence Spaces
  
  ## 1. Example Space A
  - **ID**: 123456
  - **Key**: EXMPL
  - **Type**: global
  - **Status**: current
  - **Created**: 1/1/2023, 12:00:00 PM
  - **Homepage ID**: 123789
  - **Description**: Example Confluence space for demonstration purposes
  - **URL**: [EXMPL](https://example.atlassian.net/wiki/spaces/EXMPL)
  - **Alias**: EXMPL
  
  ## 2. Example Space B
  - **ID**: 789012
  - **Key**: DEMO
  - **Type**: global
  - **Status**: current
  - **Created**: 2/1/2023, 10:00:00 AM
  - **Homepage ID**: 789123
  - **URL**: [DEMO](https://example.atlassian.net/wiki/spaces/DEMO)
  - **Alias**: DEMO
  
  ...
  
  ---
  ## Pagination
  *More spaces available. Use the following cursor to retrieve the next page:*
  
  `eyJpZCI6MTY3MTE2ODMsInNwYWNlU29ydE9yZGVyIjp7ImZpZWxkIjoiSUQiLCJkaXJlY3Rpb24iOiJBU0NFTkRJTkcifSwic3BhY2VTb3J0T3JkZXJWYWx1ZSI6MTY3MTE2ODN9`
  
  *For CLI: Use `--cursor "eyJpZCI6MTY3MTE2ODMsInNwYWNlU29ydE9yZGVyIjp7ImZpZWxkIjoiSUQiLCJkaXJlY3Rpb24iOiJBU0NFTkRJTkcifSwic3BhY2VTb3J0T3JkZXJWYWx1ZSI6MTY3MTE2ODN9"` to get the next page*
  *For MCP tools: Set the `cursor` parameter to retrieve the next page*
  

• Get details for a specific Confluence space:

  npx -y aashari/mcp-atlassian-confluence get-space 123456
  

  Example output:

  # Confluence Space: Example Space C
  
  > A current global space with key `DOCS` created on 3/15/2023, 10:00:00 AM.
  
  ## Basic Information
  - **ID**: 345678
  - **Key**: DOCS
  - **Type**: global
  - **Status**: current
  - **Created At**: 3/15/2023, 10:00:00 AM
  - **Author ID**: 123456:abcd1234-abcd-1234-abcd-1234abcd1234
  - **Homepage ID**: 345789
  - **Current Alias**: DOCS
  
  ## Links
  - **Web UI**: [Open in Confluence](https://example.atlassian.net/wiki/spaces/DOCS)
  
  ## Labels
  
  This space has the following labels:
  - documentation
  - example
  - reference
  
  *Space information retrieved at 3/16/2025, 1:31:45 AM*
  *To view this space in Confluence, visit: https://example.atlassian.net/wiki/spaces/DOCS*
  

Pages Commands

• List Confluence pages:

  npx -y aashari/mcp-atlassian-confluence list-pages --space-id 123456 --limit 5
  

  With filtering options:

  npx -y aashari/mcp-atlassian-confluence list-pages --space-id 123456 --status current --limit 5
  

  With pagination:

  # Get the first page with 10 results
  npx -y aashari/mcp-atlassian-confluence list-pages --space-id 123456 --limit 10
  
  # Get the next page using the cursor from the previous response
  npx -y aashari/mcp-atlassian-confluence list-pages --space-id 123456 --limit 10 --cursor "eyJpZCI6IjIyMjgyMjQ2IiwiY29udGVudE9yZGVyIjoiaWQiLCJjb250ZW50T3JkZXJWYWx1ZSI6MjIyODIyNDZ9"
  

  Example output:

  # Confluence Pages
  
  ## 1. Getting Started
  - **ID**: 456789
  - **Title**: Getting Started
  - **Space ID**: 123456
  - **Status**: current
  - **Created**: 5/12/2023, 1:31:56 PM
  - **Author ID**: 123456:abcd1234-abcd-1234-abcd-1234abcd1234
  - **URL**: [Getting Started](/spaces/DOCS/overview)
  
  ## 2. Installation Guide
  - **ID**: 456790
  - **Title**: Installation Guide
  - **Space ID**: 123456
  - **Status**: current
  - **Created**: 5/14/2023, 2:24:01 PM
  - **Author ID**: 123456:abcd1234-abcd-1234-abcd-1234abcd1234
  - **URL**: [Installation Guide](/spaces/DOCS/pages/456790/Installation+Guide)
  - **Parent ID**: 456789
  
  ...
  
  ---
  ## Pagination
  *More pages available. Use the following cursor to retrieve the next page:*
  
  `eyJpZCI6IjIyMjgyMjQ2IiwiY29udGVudE9yZGVyIjoiaWQiLCJjb250ZW50T3JkZXJWYWx1ZSI6MjIyODIyNDZ9`
  
  *For CLI: Use `--cursor "eyJpZCI6IjIyMjgyMjQ2IiwiY29udGVudE9yZGVyIjoiaWQiLCJjb250ZW50T3JkZXJWYWx1ZSI6MjIyODIyNDZ9"` to get the next page*
  *For MCP tools: Set the `cursor` parameter to retrieve the next page*
  

• Get details for a specific Confluence page:

  npx -y aashari/mcp-atlassian-confluence get-page 456789
  

  Example output:

  # Confluence Page: Getting Started
  
  > A current page in space `123456` created on 5/12/2023, 1:31:56 PM.
  
  ## Basic Information
  - **ID**: 456789
  - **Title**: Getting Started
  - **Space ID**: 123456
  - **Status**: current
  - **Created At**: 5/12/2023, 1:31:56 PM
  - **Author ID**: 123456:abcd1234-abcd-1234-abcd-1234abcd1234
  
  ## Content
  Search
  
  # Table of Contents
  
  -   [Overview](/wiki/spaces/DOCS/pages/456791/Overview)
  -   [Introduction](/wiki/spaces/DOCS/pages/456792/Introduction)
  ...
  
  ## Labels
  *No labels assigned to this page*
  
  ## Links
  - **Web UI**: [Open in Confluence](https://example.atlassian.net/wiki/spaces/DOCS/overview)
  
  *Page information retrieved at 3/16/2025, 2:51:32 PM*
  *To view this page in Confluence, visit: https://example.atlassian.net/wiki/spaces/DOCS/overview*
  

Search Commands

# Search for pages containing "API" in the title
npx -y aashari/mcp-atlassian-confluence search "title ~ \"API\""

# Search for pages in a specific space
npx -y aashari/mcp-atlassian-confluence search "space = \"SHOP\""

# Search for pages with a specific label
npx -y aashari/mcp-atlassian-confluence search "label = \"documentation\""

# Search with multiple conditions (using AND, OR)
npx -y aashari/mcp-atlassian-confluence search "space = \"SHOP\" AND title ~ \"API\""

# Limit search results
npx -y aashari/mcp-atlassian-confluence search "type = \"page\"" --limit 5

# Pagination with cursor
npx -y aashari/mcp-atlassian-confluence search "type = \"page\"" --cursor "eyJpZCI6IjE2NzExNzQ3IiwiY29udGVudE9yZGVyIjoiaWQiLCJjb250ZW50T3JkZXJWYWx1ZSI6MTY3MTE3NDd9"

About MCP

For detailed information about the Model Context Protocol (MCP), including core concepts, architecture, and implementation guides, please refer to the official MCP documentation.

For Developers

If you're interested in developing or extending this project, please refer to the Development Guide for detailed information on:

• Prerequisites and installation
• Project structure
• Configuration options
• Adding new features
• Testing and best practices
• And more

License

ISC