@chinchillaenterprises/mcp-confluence

MCP Confluence

An MCP (Model Context Protocol) server that provides full read/write access to Atlassian Confluence spaces and pages. This server allows AI assistants like Claude to interact with your Confluence content, search for information, create and update pages, manage attachments, and more.

Version 2.0.0 - Now with full write capabilities!

Quick Start

npm install -g @chinchillaenterprises/mcp-confluence

Add to your Claude configuration:

{
  "servers": {
    "confluence": {
      "command": "mcp-confluence",
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_EMAIL": "[e-mail]",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Features

Read Operations (v1.0.0)

Space Management

• List Spaces - Browse all accessible Confluence spaces with filtering options
• Get Space Details - Retrieve metadata and information about specific spaces
• Search Spaces - Find spaces by name or key

Page Operations

• List Pages - Browse pages within a space with pagination
• Get Page Content - Retrieve full page content and metadata
• Search Pages - Search for pages using Confluence Query Language (CQL)
• Navigate Page Hierarchy - Get page tree structure and child pages

Content & Attachments

• Get Formatted Content - Retrieve page content in different formats (storage, view, export)
• List Attachments - Browse files attached to pages
• Get Attachment Info - Retrieve attachment metadata

Search & Navigation

• Global Search - Search across all spaces using CQL
• Page History - View version history of pages
• Labels - Get labels/tags associated with pages

Write Operations (v2.0.0) 🆕

Page Management

• Create Pages - Create new pages with content, set parent pages, and status
• Update Pages - Modify existing page content, titles, with version control
• Delete Pages - Move pages to trash or permanently delete them

Space Management

• Create Spaces - Create new Confluence spaces (global or personal)

Content Organization

• Add Labels - Tag pages with multiple labels
• Remove Labels - Remove specific labels from pages
• Move Pages - Bulk move pages between spaces or parent pages

Attachments

• Upload Attachments - Upload files to pages with optional comments
• Delete Attachments - Remove attachments from pages

Prerequisites

1. Confluence API Token

• Go to Atlassian Account Settings
• Click "Create API token"
• Give it a descriptive name (e.g., "MCP Confluence Integration")
• Copy the token - you'll need it for configuration

2. Confluence URL

Your Confluence URL is typically:

• Cloud: https://your-domain.atlassian.net
• Server/DC: https://confluence.your-company.com

3. Permissions

Your Confluence user account needs:

• Read access to spaces and pages you want to query
• View permissions for content you want to search
• Write permissions for creating/updating pages (v2.0.0)
• Space admin permissions for creating spaces (v2.0.0)

Available Tools

Space Management

confluence_list_spaces

List all accessible Confluence spaces.

Parameters:

• limit (optional): Maximum number of spaces to return (default: 100)
• start (optional): Starting index for pagination
• type (optional): Type of spaces - "global" or "personal"
• status (optional): Status filter - "current" or "archived"

Example:

List the first 10 global spaces

confluence_get_space

Get details and metadata for a specific space.

Parameters:

• spaceKey (required): Space key (e.g., 'TEAM', 'DOC')

Example:

Get details for the ENGINEERING space

confluence_search_spaces

Search spaces by name or key.

Parameters:

• query (required): Search query for space name or key
• limit (optional): Maximum number of results (default: 25)

Example:

Search for spaces containing "product"

Page Operations

confluence_list_pages

List pages in a space with pagination support.

Parameters:

• spaceKey (required): Space key to list pages from
• limit (optional): Maximum number of pages (default: 100)
• start (optional): Starting index for pagination
• status (optional): Page status filter - "current", "trashed", or "draft"

Example:

List all current pages in the DOC space

confluence_get_page

Get page content and metadata.

Parameters:

• pageId (required): Page ID to retrieve
• expand (optional): Additional data to expand (e.g., ['body.storage', 'version', 'ancestors'])

Example:

Get the page with ID 12345 including its content and version info

confluence_search_pages

Search pages using Confluence Query Language (CQL).

Parameters:

• query (required): CQL search query
• limit (optional): Maximum number of results (default: 25)
• start (optional): Starting index for pagination
• spaceKey (optional): Limit search to specific space

Example:

Search for pages containing "API documentation" in the TECH space

confluence_get_page_tree

Get page hierarchy and children.

Parameters:

• pageId (required): Parent page ID
• depth (optional): Tree depth - "all" or "children" (default: "children")

Example:

Get all child pages under page ID 67890

Content & Attachments

confluence_get_page_content

Get formatted page content in various formats.

Parameters:

• pageId (required): Page ID to get content for
• format (optional): Content format - "storage", "view", or "export_view" (default: "storage")

Example:

Get the rendered HTML content of page 12345

confluence_list_attachments

List attachments on a page.

Parameters:

• pageId (required): Page ID to list attachments for
• limit (optional): Maximum number of attachments (default: 100)
• start (optional): Starting index for pagination

Example:

List all attachments on page 12345

confluence_get_attachment

Get attachment metadata (not the file content).

Parameters:

• attachmentId (required): Attachment ID to retrieve

Example:

Get metadata for attachment ID abc123

Search & Navigation

confluence_global_search

Search across all spaces using CQL.

Parameters:

• query (required): CQL search query
• limit (optional): Maximum number of results (default: 25)
• start (optional): Starting index for pagination
• includeArchivedSpaces (optional): Include archived spaces in search

Example:

Search for "deployment guide" across all spaces

confluence_get_page_history

Get page version history.

Parameters:

• pageId (required): Page ID to get history for
• limit (optional): Maximum number of versions (default: 20)

Example:

Get the last 10 versions of page 12345

confluence_list_labels

Get labels/tags for a page.

Parameters:

• pageId (required): Page ID to get labels for

Example:

Get all labels for page 12345

Write Operations 🆕

confluence_create_page

Create a new page in Confluence.

Parameters:

• spaceKey (required): Space key where page will be created
• title (required): Page title
• content (required): Page content in storage format (HTML or wiki markup)
• parentId (optional): Parent page ID (creates at space root if not provided)
• status (optional): Page status - "current" or "draft" (default: "current")

Example:

Create a page titled "API Guide" in the TECH space with some HTML content

confluence_update_page

Update an existing page with version control.

Parameters:

• pageId (required): Page ID to update
• version (required): Current version number for conflict detection
• title (optional): New page title
• content (optional): New page content in storage format
• message (optional): Version update message

Example:

Update page 12345 with new content (current version is 3)

confluence_delete_page

Delete a page (move to trash or permanently delete).

Parameters:

• pageId (required): Page ID to delete
• purge (optional): Permanently delete instead of moving to trash (default: false)

Example:

Move page 12345 to trash

confluence_create_space

Create a new Confluence space.

Parameters:

• key (required): Space key (e.g., 'TEAM', must be unique)
• name (required): Space name
• description (optional): Space description
• type (optional): Space type - "global" or "personal" (default: "global")

Example:

Create a new space with key "PROJ" named "Project Documentation"

confluence_add_labels

Add labels to a page.

Parameters:

• pageId (required): Page ID to add labels to
• labels (required): Array of label names to add

Example:

Add labels ["important", "api", "documentation"] to page 12345

confluence_remove_labels

Remove labels from a page.

Parameters:

• pageId (required): Page ID to remove labels from
• labels (required): Array of label names to remove

Example:

Remove labels ["outdated", "draft"] from page 12345

confluence_upload_attachment

Upload a file attachment to a page.

Parameters:

• pageId (required): Page ID to attach file to
• filePath (required): Path to file to upload
• comment (optional): Attachment comment

Example:

Upload "/path/to/diagram.png" to page 12345 with comment "Architecture diagram v2"

confluence_delete_attachment

Delete an attachment.

Parameters:

• attachmentId (required): Attachment ID to delete

Example:

Delete attachment abc123

confluence_move_pages

Move pages to another space or parent.

Parameters:

• pageIds (required): Array of page IDs to move
• targetSpaceKey (required): Target space key
• targetParentId (optional): Target parent page ID

Example:

Move pages [12345, 67890] to space "ARCHIVE"

CQL (Confluence Query Language) Examples

The search tools support CQL for powerful queries:

# Find pages by title
title ~ "API Documentation"

# Find pages in a specific space
space = "TECH" AND title ~ "Guide"

# Find pages modified in the last week
lastmodified > now("-7d")

# Find pages by label
label = "important" AND type = page

# Find pages by creator
creator = "john.doe" AND space = "PROJ"

# Complex queries
(label = "api" OR label = "documentation") AND lastmodified > "2024-01-01"

Troubleshooting

Authentication Errors

401 Unauthorized

• Verify your API token is correct
• Check that your email matches the Confluence account
• Ensure the token hasn't expired

403 Forbidden

• Verify you have read permissions for the requested content
• Check if the space or page has restricted access

Connection Issues

ECONNREFUSED

• Check your CONFLUENCE_URL is correct
• Verify you can access Confluence in a browser
• Check for proxy/firewall restrictions

API Limitations

Rate Limiting

• Confluence Cloud has rate limits
• The server includes a 30-second timeout
• For large operations, use pagination

Response Size

• Large pages may exceed response limits
• Use specific expand parameters to limit data
• Consider using export_view format for cleaner content

Security Considerations

• API Token Storage: Store your API token securely, never commit it to version control
• Permissions: The server has the same access as the authenticated user
• Write Operations: Version 2.0.0 can modify content - use with appropriate permissions
• Data Privacy: Be mindful of sensitive information in your Confluence instance
• Version Control: Update operations require version numbers to prevent conflicts

Version History

v2.0.0 🆕

• Added full write capabilities
• Create, update, and delete pages
• Create spaces
• Upload and delete attachments
• Add and remove labels
• Bulk page move operations
• Enhanced error handling for write operations

v1.0.0

• Initial release with read-only operations
• Support for spaces, pages, attachments, and search
• Full CQL search capability
• Confluence Cloud and Server compatibility

Support

For issues, feature requests, or contributions, please visit: https://github.com/ChinchillaEnterprises/ChillMCP/issues

License

MIT - See LICENSE file for details