🌐 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:

For Cursor IDE

Add this configuration to your Cursor IDE MCP settings:

For Any MCP Client

Use this configuration pattern for any MCP-compatible client:

🔑 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:

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:

Configuration

Create a .env file with the following variables:

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:

MCP Inspector

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

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:

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:

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:

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:

📁 Project Structure (v0.3.0 - Optimized Architecture)

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:

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

TypeScript Errors

📝 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