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

$3

``bash
npm install -g mcp-confluence-server
`

$3

#### 1. Clone the repository

`bash
git clone
cd mcp-confluence-server
`

#### 2. Install dependencies

`bash
npm install
`

#### 3. Build the project

`bash
npm run build
`

Configuration

$3

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

$3

#### Linux/macOS

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

#### Windows

`cmd
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:

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

Usage

$3

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:

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

$3

The server communicates over stdio transport. Run it directly:

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

Available Tools

$3

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:

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

$3

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

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:

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

$3

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

$3

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)

$3

List available Confluence spaces.

Parameters:

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

$3

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:

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

$3

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:

`plain
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:

$3

`html


This is a paragraph with bold text and italic text.

This is a heading

• List item 1


• List item 2

`

$3

`html


Here's some content with a code block:



javascript
console.log("Hello, world!");
]]>

`

$3

`html


Check out this
and mention .


`

Permissions

Your Personal Access Token needs the following permissions:

$3

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

$3

- 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

$3

`bash
git clone
cd mcp-confluence-server
npm install
npm run build
`

$3

`bash
npm run dev
`

$3

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

Troubleshooting

$3

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

$3

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.