Skip to content

Dsazz/mcp-confluence

BranchesTags

Repository files navigation

🌐 Confluence MCP Server

TypeScript Bun Confluence MIT License MCP

A powerful Model Context Protocol (MCP) server that brings Atlassian Confluence integration directly to any editor or application that supports MCP

✨ 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

Click here if you want to develop or customize this MCP server

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

Tool Description Parameters Returns
confluence_get_spaces List accessible Confluence spaces with optional filtering See space parameters below Markdown-formatted list of spaces
confluence_get_space_by_key Get specific space information by space key spaceKey, optional expand flags Markdown-formatted space details
confluence_get_pages_by_space Get all pages within a specific space spaceId, optional pagination Markdown-formatted page list
confluence_get_page Get detailed information about a specific page with content pageId, optional content flags Markdown-formatted page details
confluence_get_child_pages Get child pages of a specific page for hierarchy navigation pageId, optional pagination Markdown-formatted child pages
confluence_search Search pages using text queries or CQL (renamed from search_pages) See search parameters below Markdown-formatted search results
confluence_create_page Create a new page in Confluence See page creation parameters Markdown-formatted page details
confluence_update_page Update an existing page in Confluence See page update parameters Markdown-formatted page details
confluence_delete_page Delete a page from Confluence pageId Confirmation message

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

Command Description
bun dev Run the server in development mode with hot reload
bun build Build the project for production
bun start Start the production server
bun format Format code using Biome
bun lint Lint code using Biome
bun check Run Biome checks on code
bun typecheck Run TypeScript type checking
bun test Run tests
bun inspect Start the MCP Inspector for debugging

🔧 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

📄 License

MIT © Stanislav Stepanenko

Built with ❤️ for a better developer experience

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

6 tags

Packages

 
 
 

Contributors

Languages