@dsazz/mcp-confluence v0.3.1

🌐 Confluence MCP Server

✨ Features

🚀 New in v0.3.0 - Optimized Architecture

• 9 Strategic MCP Tools - Optimized from 8 tools with enhanced workflow capabilities
• Domain-Based Architecture - Clean separation into 3 domains: Spaces, Pages, and Search
• Enhanced Navigation - New tools for space lookup, page hierarchy, and content discovery
• Improved Performance - 1871 tests passing with optimized build process

📚 Access Confluence Directly From Your Editor

• Browse your Confluence spaces without leaving your IDE
• Get detailed page information with formatted content
• Navigate page hierarchies with child page discovery
• Create, update, and manage Confluence content directly

🔍 Powerful Search Capabilities

• Search pages using text queries or advanced CQL (Confluence Query Language)
• Support for space filtering, content type filtering, and result ordering
• Rich markdown formatting with page previews and direct links
• Renamed confluence_search_pages to confluence_search for simplicity

📝 Smart Content Processing

• Automatic conversion of Confluence's storage format to readable markdown
• Support for formatted text, tables, macros, and attachments
• Full CRUD operations for page management
• Strategic workflow tools for better user experience

🚀 Quick Start

Installation

The easiest way to use this MCP server is to install it directly via npm/bunx. No local setup required!

For Claude Desktop

Add this configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

For Cursor IDE

Add this configuration to your Cursor IDE MCP settings:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

For Any MCP Client

Use this configuration pattern for any MCP-compatible client:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

🔑 Getting Your Confluence API Token

1. Go to Atlassian API Tokens
2. Click "Create API token"
3. Give it a name (e.g., "MCP Confluence")
4. Copy the token and use it in your configuration
5. Important: Use the token exactly as provided (no quotes needed in the env section)

Alternative: Using npx instead of bunx

If you prefer npx over bunx, you can also use:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "npx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

Testing Your Setup

After adding the configuration:

1. Restart your MCP client (Claude Desktop, Cursor, etc.)
2. Try this command to test the connection:

   Show me my Confluence spaces.

That's it! You're ready to use Confluence directly from your MCP client.

🛠️ Development Setup

Development Installation

For development or customization:

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

# Install dependencies
bun install

# Build the project
bun run build

# Set up environment variables
cp .env.example .env
# Edit .env with your Confluence credentials

Configuration

Create a .env file with the following variables:

CONFLUENCE_HOST_URL=https://your-domain.atlassian.net
CONFLUENCE_USER_EMAIL=your-email@example.com
CONFLUENCE_API_TOKEN=your-confluence-api-token
NODE_ENV=development

Development Tools

Code Quality Tools

The project uses Biome for code formatting and linting, replacing the previous ESLint setup. Biome provides:

• Fast, unified formatting and linting
• TypeScript-first tooling
• Zero configuration needed
• Consistent code style enforcement

To format and lint your code:

# Format code
bun format

# Check code for issues
bun check

# Type check
bun typecheck

MCP Inspector

The MCP Inspector is a powerful tool for testing and debugging your MCP server.

# Run the inspector (no separate build step needed)
bun run inspect

The inspector automatically:

• Loads environment variables from .env
• Cleans up occupied ports (5175, 3002)
• Builds the project when needed
• Starts the MCP server with your configuration
• Launches the inspector UI

Visit the inspector at http://localhost:5175?proxyPort=3002

The inspector UI allows you to:

• View all available MCP capabilities
• Execute tools and examine responses
• Analyze the JSON communication
• Test with different parameters

For more details, see the MCP Inspector GitHub repository.

🧰 Available Tools

🌟 Strategic Workflow Tools

Space Parameters

The confluence_get_spaces tool supports these parameters:

Basic Options:

• type: String ("global" or "personal", optional) - Filter by space type
• limit: Number (1-100, default: 25) - Maximum number of spaces to return
• start: Number (default: 0) - Pagination offset for large result sets

Examples:

# Basic usage - get all accessible spaces
confluence_get_spaces

# Get only global spaces
confluence_get_spaces type:"global" limit:10

# Pagination example
confluence_get_spaces start:25 limit:25

Page Parameters

The confluence_get_page tool supports these parameters:

Required:

• pageId: String - The ID of the page to retrieve

Content Options:

• includeContent: Boolean (default: true) - Include full page content
• includeComments: Boolean (default: false) - Include comment count
• expand: String (optional) - Additional fields to expand (comma-separated)

Examples:

# Basic usage with content
confluence_get_page 12345

# Get page without content
confluence_get_page 12345 includeContent:false

# Get page with comments and extra data
confluence_get_page 12345 includeComments:true expand:"version,space"

Search Parameters

The confluence_search tool supports both simple and advanced search:

Basic Search:

• query: String - Text search query (searches titles and content)
• spaceKey: String (optional) - Limit search to specific space
• type: String ("page" or "blogpost", optional) - Content type filter

Advanced Search (CQL):

• query: String - Full CQL query for advanced searches
• Examples: text~"specific phrase", type=page AND space.key="DEV"

Result Options:

• limit: Number (1-100, default: 25) - Maximum number of results
• start: Number (default: 0) - Pagination offset
• orderBy: String ("relevance", "created", "modified", "title") - Sort order

Examples:

# Simple text search
confluence_search query:"project documentation"

# Search in specific space
confluence_search query:"API guide" spaceKey:"DEV"

# Advanced CQL search
confluence_search query:'text~"user guide" AND type=page'

# Search with custom ordering
confluence_search query:"meeting notes" orderBy:"modified" limit:10

Page Management Parameters

Page Creation (confluence_create_page):

• spaceId: String - The ID of the space where the page will be created
• title: String - The title of the new page
• content: String - The content of the page (supports Confluence storage format)
• parentPageId: String (optional) - The ID of the parent page
• status: String ("current" or "draft", default: "current") - Page status

Page Update (confluence_update_page):

• pageId: String - The ID of the page to update
• title: String (optional) - New title for the page
• content: String (optional) - New content for the page
• versionNumber: Number - Current version number of the page
• versionMessage: String (optional) - Message describing the changes

Examples:

# Create a new page
confluence_create_page spaceId:"123456" title:"New Documentation" content:"<p>Initial content</p>"

# Update an existing page
confluence_update_page pageId:"789012" title:"Updated Title" content:"<p>Updated content</p>" versionNumber:2

# Get child pages for navigation
confluence_get_child_pages pageId:"123456" limit:10

📁 Project Structure (v0.3.0 - Optimized Architecture)

 src/
  ├── core/                    # Core functionality and configurations
  │   ├── errors/              # Error handling utilities
  │   ├── logging/             # Logging infrastructure
  │   ├── responses/           # Response formatting
  │   ├── server/              # MCP server setup
  │   ├── tools/               # Base tool patterns
  │   └── utils/               # General utilities
  ├── features/                # Feature implementations
  │   └── confluence/          # Confluence integration
  │       ├── client/          # HTTP client infrastructure
  │       │   ├── config/      # Client configuration
  │       │   ├── errors/      # Client-specific errors
  │       │   ├── http/        # HTTP client implementations
  │       │   │   ├── utils/   # HTTP utilities
  │       │   │   ├── v1/      # V1 API client (search)
  │       │   │   └── v2/      # V2 API client (CRUD)
  │       │   └── responses/   # Response models
  │       ├── domains/         # Domain-based architecture (NEW)
  │       │   ├── spaces/      # Space management domain
  │       │   │   ├── handlers/     # Space operation handlers
  │       │   │   ├── models/       # Space data models
  │       │   │   ├── use-cases/    # Space business logic
  │       │   │   ├── validators/   # Space validation
  │       │   │   └── formatters/   # Space response formatting
  │       │   ├── pages/       # Page management domain
  │       │   │   ├── handlers/     # Page operation handlers
  │       │   │   ├── models/       # Page data models
  │       │   │   ├── use-cases/    # Page business logic
  │       │   │   ├── validators/   # Page validation
  │       │   │   └── formatters/   # Page response formatting
  │       │   └── search/      # Search domain
  │       │       ├── handlers/     # Search operation handlers
  │       │       ├── models/       # Search data models
  │       │       ├── use-cases/    # Search business logic
  │       │       ├── validators/   # Search validation
  │       │       └── formatters/   # Search response formatting
  │       ├── shared/          # Shared utilities across domains
  │       │   ├── formatters/  # Common formatters
  │       │   └── validators/  # Common validators
  │       └── tools/           # MCP tool orchestration
  │           ├── handlers.ts  # Unified tool handlers
  │           ├── mcp.ts       # MCP tool definitions
  │           └── routing.ts   # Tool routing logic
  └── test/                    # Test suite (1871 tests)
      ├── integration/         # Integration tests
      ├── unit/               # Unit tests (domain-organized)
      │   ├── core/           # Core functionality tests
      │   └── features/       # Feature tests (by domain)
      │       └── confluence/
      │           └── domains/ # Domain-specific tests
      │               ├── spaces/   # Space domain tests
      │               ├── pages/    # Page domain tests
      │               └── search/   # Search domain tests
      └── utils/              # Test utilities

Architecture Overview

The Confluence MCP Server uses a dual-client architecture for optimal API version management:

• V1 Client (http-client-v1.impl.ts): Handles search operations and CQL queries
• V2 Client (http-client-v2.impl.ts): Manages CRUD operations for spaces and pages
• Operation Router (operation.router.ts): Intelligently routes requests to the appropriate API version
• Factory Pattern (http-client.factory.ts): Provides clean dependency injection for clients

This architecture ensures:

• Optimal Performance: Each operation uses the most suitable API version
• Future Compatibility: Easy to add new API versions or deprecate old ones
• Clean Separation: Clear boundaries between different API capabilities
• Type Safety: Full TypeScript support across all client implementations

NPM Scripts

🔧 Troubleshooting

NPM Installation Issues

Package Not Found

If you get a "package not found" error:

# Make sure you're using the correct scoped package name
bunx @dsazz/mcp-confluence@latest

# Or try with explicit npm registry
npm install -g @dsazz/mcp-confluence --registry https://registry.npmjs.org

Environment Variables Not Found

If the server fails to start with environment variable errors:

1. For bunx usage: Create a .env file in your working directory:

   # Create .env file in your current directory
   echo "CONFLUENCE_HOST_URL=https://your-domain.atlassian.net" > .env
   echo "CONFLUENCE_USER_EMAIL=your-email@example.com" >> .env
   echo "CONFLUENCE_API_TOKEN=your-api-token" >> .env

2. For MCP configuration: Set environment variables in your MCP config:

   {
     "mcpServers": {
       "Confluence Tools": {
         "command": "bunx",
         "args": ["-y", "@dsazz/mcp-confluence@latest"],
         "env": {
           "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
           "CONFLUENCE_USER_EMAIL": "your-email@example.com",
           "CONFLUENCE_API_TOKEN": "your-api-token"
         }
       }
     }
   }

API Connection Issues

Invalid Credentials

• Verify your Confluence API token is correct
• Ensure your email matches your Atlassian account
• Check that your Confluence URL is correct (include https://)

Network/Firewall Issues

• Ensure your network allows connections to your Confluence instance
• Check if your organization requires VPN access
• Verify firewall settings allow outbound HTTPS connections

Development Issues

Build Failures

# Clear dependencies and reinstall
rm -rf node_modules bun.lockb
bun install

# Clean build
rm -rf dist
bun run build

TypeScript Errors

# Run type checking
bun run typecheck

# Check for linting issues
bun run check

📝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Development workflow
• Branching strategy
• Commit message format
• Pull request process
• Code style guidelines

📘 Resources

• Model Context Protocol Documentation
• MCP TypeScript SDK
• MCP Specification
• MCP Inspector
• Confluence REST API

📄 License

MIT © Stanislav Stepanenko