MCP Confluence Server

A Model Context Protocol (MCP) server that provides tools for interacting with Atlassian Confluence. This server enables AI applications to read, create, update, and manage Confluence content through standardized MCP tools.

Features

• Content Operations: Get, search, create, and update Confluence pages and blog posts
• File Conversion: Convert Markdown and Word documents directly to Confluence pages
• Attachment Management: Upload files and attachments to Confluence content
• Space Management: List available Confluence spaces
• CQL Search: Use Confluence Query Language for advanced content searching
• Secure Authentication: Uses Personal Access Tokens for secure API access

Prerequisites

• Node.js 18 or higher
• Access to a Confluence instance (Cloud or Server/Data Center)
• A Confluence Personal Access Token with appropriate permissions

Installation

From npm (Recommended)

npm install -g mcp-confluence-server

From Source

1. Clone the repository

git clone <repository-url>
cd mcp-confluence-server

2. Install dependencies

npm install

3. Build the project

npm run build

Configuration

Environment Variables

The server requires two environment variables:

• CONFLUENCE_BASE_URL: The base URL of your Confluence instance

  • Example: https://your-company.atlassian.net (for Confluence Cloud)
  • Example: https://confluence.your-company.com (for Server/Data Center)

• CONFLUENCE_PAT: Your Personal Access Token

  • For Confluence Cloud: Create an API token
  • For Server/Data Center: Create a Personal Access Token

Setting Environment Variables

Linux/macOS

export CONFLUENCE_BASE_URL="https://your-company.atlassian.net"
export CONFLUENCE_PAT="your-personal-access-token"

Windows

set CONFLUENCE_BASE_URL=https://your-company.atlassian.net
set CONFLUENCE_PAT=your-personal-access-token

Using .env file

Create a .env file in your project directory:

CONFLUENCE_BASE_URL=https://your-company.atlassian.net
CONFLUENCE_PAT=your-personal-access-token

Usage

With Claude Desktop

Add the server to your Claude Desktop configuration file:

Location of config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "confluence": {
      "command": "mcp-confluence-server",
      "env": {
        "CONFLUENCE_BASE_URL": "https://your-company.atlassian.net",
        "CONFLUENCE_PAT": "your-personal-access-token"
      }
    }
  }
}

With other MCP clients

The server communicates over stdio transport. Run it directly:

CONFLUENCE_BASE_URL="https://your-company.atlassian.net" CONFLUENCE_PAT="your-token" mcp-confluence-server

Available Tools

1. confluence-get-content

Retrieve Confluence content by ID.

Parameters:

• contentId (string, required): ID of the content to retrieve
• expand (array of strings, optional): Additional fields to expand (e.g., body.storage, space, version)

Example usage:

Get the content with ID "123456" including the body and version information

2. confluence-search-content

Search Confluence content using CQL (Confluence Query Language).

Parameters:

• cql (string, required): CQL query string
• limit (number, optional): Maximum number of results (default: 25)

Example CQL queries:

• space=DEV AND type=page - All pages in DEV space
• title ~ "API documentation" - Content with "API documentation" in title
• space=PROD AND created >= "2024-01-01" - Recent content in PROD space

3. confluence-create-content

Create new Confluence content (page or blog post).

Parameters:

• type (string, required): "page" or "blogpost"
• title (string, required): Title of the content
• spaceKey (string, required): Key of the space to create content in
• body (string, required): Content body in Confluence storage format (HTML-like)
• parentId (string, optional): ID of parent page for hierarchical pages

Example:

Create a new page titled "API Documentation" in the DEV space with some sample content

4. confluence-update-content

Update existing Confluence content.

Parameters:

• id (string, required): ID of the content to update
• title (string, required): New title for the content
• body (string, required): New content body in Confluence storage format
• version (number, required): Current version number of the content

5. confluence-upload-attachment

Upload an attachment to Confluence content.

Parameters:

• contentId (string, required): ID of the content to attach the file to
• filename (string, required): Name of the file to upload
• data (string, required): File content as base64 encoded string or plain text
• contentType (string, optional): MIME type of the file
• comment (string, optional): Comment for the attachment
• isBase64 (boolean, optional): Whether the data is base64 encoded (default: false)

6. confluence-get-spaces

List available Confluence spaces.

Parameters:

• limit (number, optional): Maximum number of spaces to return (default: 25)

7. confluence-content-from-markdown

Create or update Confluence content from Markdown files with automatic XHTML conversion.

Parameters:

• filePath (string, required): Path from home directory to markdown file (e.g., "~/Documents/file.md")
• action (string, optional): Action to take - "save" (save to file), "update" (update existing content), "create" (create new page). Default: "save"
• contentId (string, optional): Required for "update" action - ID of content to update
• title (string, optional): Required for "update" action - Title for the content
• version (number, optional): For "update" action - Current version number (auto-increments if not provided)
• spaceKey (string, optional): Required for "create" action - Space key where to create content
• newTitle (string, optional): Required for "create" action - Title for new content
• parentId (string, optional): For "create" action - Parent page ID for sub-pages

Example usage:

Convert ~/Documents/README.md to Confluence format and create a new page in the DEV space

8. confluence-content-from-docx

Create or update Confluence content from Microsoft Word .docx files with automatic XHTML conversion.

Parameters:

• filePath (string, required): Path from home directory to DOCX file (e.g., "~/Documents/file.docx")
• action (string, optional): Action to take - "save" (save to file), "update" (update existing content), "create" (create new page). Default: "save"
• contentId (string, optional): Required for "update" action - ID of content to update
• title (string, optional): Required for "update" action - Title for the content
• version (number, optional): For "update" action - Current version number (auto-increments if not provided)
• spaceKey (string, optional): Required for "create" action - Space key where to create content
• newTitle (string, optional): Required for "create" action - Title for new content
• parentId (string, optional): For "create" action - Parent page ID for sub-pages
• options (object, optional): Conversion options including preserveImages, convertTables, confluenceMacros, etc.

Example usage:

Convert ~/Documents/report.docx and update existing page ID 123456789 with the converted content

Confluence Storage Format

When creating or updating content, you need to provide the body in Confluence's storage format. This is an HTML-like format with special Confluence macros.

Examples:

Simple HTML content

<p>This is a paragraph with <strong>bold text</strong> and <em>italic text</em>.</p>
<h2>This is a heading</h2>
<ul>
  <li>List item 1</li>
  <li>List item 2</li>
</ul>

With Confluence macros

<p>Here's some content with a code block:</p>
<ac:structured-macro ac:name="code" ac:schema-version="1">
  <ac:parameter ac:name="language">javascript</ac:parameter>
  <ac:plain-text-body><![CDATA[
console.log("Hello, world!");
  ]]></ac:plain-text-body>
</ac:structured-macro>

With links and mentions

<p>Check out this <ac:link><ri:page ri:content-title="Other Page" /></ac:link> 
and mention <ac:link><ri:user ri:userkey="user123" /></ac:link>.</p>

Permissions

Your Personal Access Token needs the following permissions:

Confluence Cloud

• Read: View pages, blog posts, and spaces
• Write: Create and edit pages and blog posts
• Attachment: Upload and manage attachments

Confluence Server/Data Center

• Confluence: Can use Confluence
• Space permissions: Read/Write access to relevant spaces

Error Handling

The server provides detailed error messages for common issues:

• Configuration errors: Missing or invalid environment variables
• Authentication errors: Invalid or expired tokens
• API errors: Detailed Confluence API error messages
• Permission errors: Insufficient permissions for requested operations

Development

Building from Source

git clone <repository-url>
cd mcp-confluence-server
npm install
npm run build

Running in Development Mode

npm run dev

Project Structure

src/
├── index.ts          # Main server entry point
├── config.ts         # Environment configuration
├── confluence-client.ts  # Confluence API client
└── tools.ts          # MCP tool implementations

Troubleshooting

Common Issues

1. "CONFLUENCE_BASE_URL environment variable is required"

   • Ensure you've set the environment variable correctly
   • Check for typos in the variable name

2. "Invalid CONFLUENCE_BASE_URL"

   • Ensure the URL includes the protocol (https://)
   • Remove any trailing slashes from the URL

3. "Confluence API error: 401 Unauthorized"

   • Check if your Personal Access Token is valid
   • Ensure the token has the required permissions

4. "Confluence API error: 403 Forbidden"

   • Your token doesn't have permission to access the requested resource
   • Check space permissions and token scope

5. "Content not found" errors

   • Verify the content ID or space key is correct
   • Ensure the content exists and you have permission to access it

Debug Mode

For detailed debugging, you can examine the server logs. The server outputs status information to stderr while keeping stdout clear for MCP communication.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and feature requests, please use the GitHub issue tracker.