Managing Confluence

Managing Confluence

Model Context Protocol server for Confluence pages, spaces, and content management.

Overview

The Atlassian MCP server provides 13 tools for Confluence operations through the Model Context Protocol. It automatically connects to your Confluence instance when properly configured.

Configuration

Required Setup

The MCP server requires API credentials in ~/.atlassian-mcp.json:

{
  "domain": "your-domain.atlassian.net",
  "email": "your-email@example.com",
  "apiToken": "your-api-token-here"
}

Create an API token: https://id.atlassian.com/manage-profile/security/api-tokens

Set permissions:

chmod 600 ~/.atlassian-mcp.json

Available Operations

Spaces

List Spaces:

• View all accessible Confluence spaces
• Supports pagination for large instances
• Returns space keys, names, and types

Pages

Create Page:

• Create new pages in any space
• Set title, content (in Confluence storage format), and parent page
• Supports both top-level and nested pages

Get Page:

• Retrieve page content by ID or title
• Returns full content including metadata
• Access page properties and versions

Update Page:

• Modify existing page content and title
• Requires page ID and version number
• Preserves page history

Delete Page:

• Remove pages from Confluence
• Requires page ID
• Moves page to trash (can be restored)

List Child Pages:

• Get all child pages of a parent page
• Navigate page hierarchies
• Returns page IDs and titles

Get Page Ancestors:

• Retrieve full page ancestor chain
• Navigate up the page tree
• Useful for breadcrumb generation

Search

Search Content:

• Use CQL (Confluence Query Language) for powerful searches
• Search across pages, spaces, and content
• Filter by type, space, label, and more

CQL Examples:

type=page and space=MYSPACE
title ~ "meeting notes" and created > now("-30d")
label = "documentation" and space in (SPACE1, SPACE2)

Comments

Create Comment:

• Add comments to pages
• Supports threaded discussions
• Requires page ID

List Comments:

• View all comments on a page
• Returns comment content and authors
• Includes nested replies

Labels

Add Label:

• Tag pages with labels for organization
• Supports multiple labels per page
• Enables label-based search

Remove Label:

• Delete labels from pages
• Clean up outdated tags

List Labels:

• View all labels on a page
• Useful for content categorization

Users

Search Users:

• Find users by name, email, or display name
• Get user account IDs for permissions
• Returns user profiles

Common Patterns

Creating a New Page

When creating a Confluence page, the MCP server will handle the operation through its available tools. Simply request the creation with the necessary details:

• Space key: The Confluence space where the page should be created
• Title: The page title
• Content: Page content in Confluence storage format (can be HTML or Markdown-like)
• Parent page ID (optional): For nested pages

Searching for Pages

Use CQL queries to find specific content:

• Search by title: title ~ "keyword"
• Search by space: space = SPACEKEY
• Search by date: created > now("-7d")
• Combine filters: type=page and space=DOCS and label="important"

Updating Existing Content

To update a page:

1. First retrieve the page to get its current version
2. Modify the content as needed
3. Update the page with new content and incremented version number

Managing Page Hierarchies

Navigate page relationships:

• List child pages to see what's under a parent
• Get ancestors to understand page location in the space
• Create nested pages by specifying a parent page ID

Important Notes

Content Format

Confluence uses storage format for page content:

• HTML-like structure with Confluence-specific elements
• Use <ac:structured-macro> for macros
• Tables, images, and formatting use XHTML syntax

Permissions

• MCP operations respect Confluence permissions
• You can only access spaces and pages you have permission to view
• Create/update/delete operations require appropriate permissions

Rate Limiting

• Atlassian Cloud APIs have rate limits
• Batch operations carefully to avoid throttling
• The MCP server handles basic rate limiting

Integration with Work Logs

When documenting Confluence work in dev/active/ logs:

• Reference pages by URL and page ID
• Note space keys for context
• Include CQL queries used for search operations
• Document any permission or access issues encountered

Troubleshooting

Authentication Errors

If you get authentication failures:

1. Verify ~/.atlassian-mcp.json exists and has correct format
2. Check API token is valid (not expired)
3. Confirm email matches your Atlassian account
4. Ensure domain includes .atlassian.net

Permission Errors

If operations fail due to permissions:

• Verify you have access to the space in Confluence web UI
• Check if page restrictions are limiting access
• Confirm your account has required permissions (view/edit/create)

Page Not Found

If pages can't be located:

• Verify space key is correct (case-sensitive)
• Check if page was deleted or moved
• Try searching with CQL to locate the page

Differences from ACLI

Use Atlassian MCP for:

• ✅ Confluence pages, spaces, and wiki content
• ✅ CQL search queries
• ✅ Page hierarchies and navigation
• ✅ Confluence comments and labels

Use ACLI for:

• ✅ Jira issues, work items, and tickets
• ✅ Jira comments and transitions
• ✅ JQL queries for Jira
• ✅ Sprints, epics, and Jira-specific features

Resources

• API Token Creation: https://id.atlassian.com/manage-profile/security/api-tokens
• Confluence REST API: https://developer.atlassian.com/cloud/confluence/rest/
• CQL Reference: https://developer.atlassian.com/cloud/confluence/cql/
• MCP Package: https://github.com/xuanxt/atlassian-mcp