Confluence MCP Server

A comprehensive Model Context Protocol (MCP) server that provides powerful Confluence Cloud integration for documentation management with Claude Code CLI and Claude Desktop.

🚀 Features

Core Documentation Operations

• Page Management: Create, read, update, and delete Confluence pages
• Content Search: Powerful search across spaces and pages
• Comment System: Add comments and replies to documentation pages
• Space Management: Create and manage Confluence spaces

Advanced Documentation Workflow

• Page Hierarchy: Manage parent-child page relationships automatically
• Content Organization: Move, copy, and organize pages across spaces
• Label Management: Tag pages with labels for better organization
• Tree Navigation: Get complete page hierarchies and navigation structures

Claude Integration & Developer Experience

• Seamless Setup: Automatic Claude Code CLI and Claude Desktop configuration
• Cloud-First: Built exclusively for Confluence Cloud (no legacy support)
• Modern Architecture: TypeScript + ESM with comprehensive error handling
• Content Formatting: Support for ADF (Atlassian Document Format) and Storage Format

📦 Installation

Installation Methods

1. From NPM (Recommended)

# Install globally
npm install -g bds-confluence-mcp
# or
pnpm add -g bds-confluence-mcp

# Run interactive setup
npx bds-confluence-mcp-setup

2. From Source

# Clone the repository
git clone https://github.com/nmindz/bds-confluence-mcp.git
cd bds-confluence-mcp

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run setup
node build/setup.js

Requirements

• Node.js 18+ (for ESM module support)
• Confluence Cloud instance with API access
• Claude Code CLI or Claude Desktop

⚙️ Configuration

Confluence Cloud Setup

1. API Token: Generate from Atlassian Account Settings
2. Base URL: Your Confluence Cloud URL (e.g., https://company.atlassian.net)
3. Email: Your Confluence account email

Environment Variables

CONFLUENCE_BASE_URL=https://your-company.atlassian.net
[email protected]
CONFLUENCE_API_TOKEN=your-api-token
CONFLUENCE_DEFAULT_SPACE=DOC  # Optional default space

Claude Integration

The setup command automatically configures:

• Claude Code CLI: ~/.claude.json
• Claude Desktop: Platform-specific MCP configuration

🛠️ Available Tools

Core Page Management

| Tool | Description | |------|-------------| | get_page | Fetch page details by ID or title | | create_page | Create new pages with content | | update_page | Update existing page content or title | | delete_page | Delete pages (trash or permanent) |

Content & Collaboration

| Tool | Description | |------|-------------| | search_content | Search across spaces and pages | | add_comment | Add comments to pages | | add_label | Tag pages with labels | | copy_page | Duplicate pages with content | | move_page | Move pages between spaces |

Hierarchy & Organization

| Tool | Description | |------|-------------| | get_child_pages | Get direct child pages | | get_page_tree | Get full page hierarchy tree | | get_space | Get space information | | create_space | Create new Confluence spaces |

💻 Usage Examples

Basic Page Operations

# In Claude conversation:
"Get the page called 'API Documentation' from the DEV space"
"Create a new page called 'Getting Started' in the DOCS space with installation instructions"
"Update page ID 12345 with the latest API changes"

Content Management

"Search for all pages about 'authentication' in the API space"
"Copy the 'Template' page to create 'New Project Setup'"
"Move the 'Old Guide' page to the ARCHIVE space"

Documentation Structure

"Get all child pages under 'User Guide'"
"Show me the full page tree starting from the homepage"
"Create a new space called 'PROJECT' for project documentation"

Advanced Workflows

"Create a documentation structure with:
- Main page: 'Product Guide'
- Child pages: 'Installation', 'Configuration', 'API Reference'
- Add labels: 'guide', 'v2.0', 'public'"

🏗️ Development

Local Development

# Clone and install
git clone <repository-url>
cd bds-confluence-mcp
npm install

# Development with .env loading
DEBUG=true npm run dev
# or
ENVIRONMENT=development npm run debug

# Build and test
npm run build
npm test

Scripts

• npm run build - Compile TypeScript with executables
• npm run debug - Run with debug mode and .env loading
• npm run test - Run complete test suite
• npm run test:ci - CI-friendly test execution
• npm run setup - Run interactive setup

Environment-Based Configuration

The server uses conditional environment loading:

• Production: Uses environment variables directly
• Development: Loads .env file when DEBUG=true or ENVIRONMENT=development

🔧 MCP Server Details

Transport

• STDIO Transport: Compatible with Claude Code CLI and Claude Desktop
• Tool Registration: Uses official MCP SDK patterns
• Error Handling: Comprehensive error handling with user-friendly messages

Architecture

• TypeScript + ESM: Modern ES module architecture
• Cloud-Only: No legacy/on-premises code (cleaner than JIRA counterpart)
• Lazy Initialization: Services initialize only when needed
• Content Formatting: Built-in ADF and Storage Format support

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript strict mode
• Use ESM modules (import/export)
• Implement comprehensive error handling
• Add tests for new features
• Update documentation

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🆘 Support

Common Issues

• Environment Variables: Ensure all required Confluence variables are set
• Claude Integration: Restart Claude after setup for changes to take effect
• API Permissions: Verify Confluence API token has necessary permissions

Troubleshooting

Claude Desktop Connection Issues

If you experience hanging or connection issues with Claude Desktop:

Option 1: Use Direct Node.js Execution (Recommended)

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["/path/to/bds-confluence-mcp/build/index.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://company.atlassian.net",
        "CONFLUENCE_EMAIL": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Option 2: Use Full Package Manager Path

{
  "mcpServers": {
    "confluence": {
      "command": "/full/path/to/pnpm",
      "args": ["exec", "bds-confluence-mcp"],
      "env": { /* your environment variables */ }
    }
  }
}

General Debugging

# Test Confluence connection
curl -u [email protected]:api-token https://company.atlassian.net/wiki/rest/api/user/current

# Debug mode (local development)
DEBUG=true node build/index.js

# Test server directly
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}},"id":0}' | node build/index.js

# Verify Claude configuration
cat ~/.claude.json  # Claude Code CLI
cat "~/Library/Application Support/Claude/claude_desktop_config.json"  # Claude Desktop

Getting Help

• Check the troubleshooting guide
• Review development documentation
• Open an issue for bugs or feature requests

🚀 Roadmap

Completed ✅

• Core page operations and content management
• Search and navigation functionality
• Space management and organization
• Claude Code CLI and Desktop integration
• Interactive setup and configuration
• Comprehensive test suite

Planned Features 🎯

• Advanced content templates
• Bulk page operations
• Attachment management
• Enhanced search filters
• Page analytics and insights

🔄 Related Projects

• bds-jira-mcp: JIRA workflow automation MCP server

Built with ❤️ by @nmindz