Mcp Confluence

mcp-confluence

[](https://github.com/n11tech/mcp-confluence/pkgs/container/mcp-confluence) [](https://github.com/n11tech/mcp-confluence/actions/workflows/docker-publish.yml)

A Node.js/TypeScript Model Context Protocol (MCP) server for Atlassian Confluence Server/Data Center.

This server enables AI systems (e.g., LLMs, AI coding assistants) to securely interact with your Confluence pages, spaces, comments, labels, attachments, and analytics in real time through both standard stdio and HTTP streaming transports.

---

Table of Contents

• [Features](#features)
• [What is MCP?](#what-is-mcp)
• [Prerequisites](#prerequisites)
• [Installation](#installation)
• [Docker (Recommended)](#docker-recommended)
• [Local Development](#local-development)
• [Configuration](#configuration)
• [Environment Variables](#environment-variables)
• [MCP Client Setup](#mcp-client-setup)
• [Transport Options](#transport-options)
• [Standard I/O Transport (Default)](#standard-io-transport-default)
• [HTTP Streaming Transport](#http-streaming-transport)
• [Security](#security)
• [API Key Authentication](#api-key-authentication)
• [LLM Compatibility: Schema Sanitizer](#llm-compatibility-schema-sanitizer)
• [Available Tools](#available-tools)
• [Usage Examples](#usage-examples)
• [Development](#development)
• [Contributing](#contributing)
• [License](#license)

---

Features

• Dual Transport Support: Choose between stdio and HTTP streaming transports
• Secure Authentication: Optional API key authentication for HTTP transport
• Comprehensive Confluence Integration: Full access to Confluence Server/Data Center APIs — pages, spaces, comments, labels, attachments, analytics, and user search
• LLM Compatible: Schema sanitizer normalizes tool schemas for Gemini, Claude, and OpenAI compatibility
• Developer Focused: Designed to help AI assistants understand and interact with your Confluence content autonomously
• Production Ready: Built with TypeScript, clean architecture, dependency injection (InversifyJS), proper error handling, and security best practices
• Container Support: Docker support for easy deployment and scaling

---

What is MCP?

Model Context Protocol (MCP) is an open standard for securely connecting AI systems to external tools and data sources. This server implements MCP for Confluence Server/Data Center, enabling AI assistants to interact with your Confluence content programmatically through standardized interfaces.

---

Prerequisites

• Node.js: Version 20.19.0 or higher
• Confluence Server/Data Center: Access with a Personal Access Token (PAT)
• Docker: (Recommended) For containerized deployment
• Git: For cloning the repository

---

Installation

Docker (Recommended)

Using Pre-built Image from GHCR

# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/n11tech/mcp-confluence:latest

# Run with stdio transport (default)
docker run -i --rm \
  -e CONFLUENCE_URL="https://your-confluence-server.com" \
  -e CONFLUENCE_TOKEN="your_personal_access_token" \
  ghcr.io/n11tech/mcp-confluence:latest

Building from Source

1. Clone the Repository:

``bash git clone https://github.com/n11tech/mcp-confluence.git cd mcp-confluence ``

1. Build the Docker Image:

``bash docker build -t mcp-confluence:latest . ``

1. Run with Docker:

``bash docker run -i --rm \ -e CONFLUENCE_URL="https://your-confluence-server.com" \ -e CONFLUENCE_TOKEN="your_personal_access_token" \ mcp-confluence:latest ``

Via npx (No Install Required)

CONFLUENCE_URL="https://your-confluence-server.com" \
CONFLUENCE_TOKEN="your_personal_access_token" \
npx mcp-confluence

Local Development

1. Clone and Install:

``bash git clone https://github.com/n11tech/mcp-confluence.git cd mcp-confluence npm install ``

1. Configure environment:

``bash cp config.template.env .env # Edit .env with your Confluence credentials ``

1. Build:

``bash npm run build ``

1. Start:

``bash npm start ``

---

Configuration

Environment Variables

| Variable | Description | Default | Required | |----------|-------------|---------|----------| | CONFLUENCE_URL | Your Confluence Server/Data Center URL | - | ✅ | | CONFLUENCE_TOKEN | Personal Access Token for Confluence authentication | - | ✅ | | CONFLUENCE_USERNAME | Username for Confluence basic authentication | - | ❌ | | CONFLUENCE_PASSWORD | Password for Confluence basic authentication | - | ❌ | | CONFLUENCE_DEFAULT_PROJECT | Default project key for operations | - | ❌ | | ENABLE_HTTP_TRANSPORT | Enable HTTP streaming transport | false | ❌ | | MCP_HTTP_PORT | HTTP server port | 3003 | ❌ | | MCP_HTTP_ENDPOINT | HTTP endpoint path | /stream | ❌ | | MCP_API_KEY | API key for HTTP authentication | - | ❌ | | LOG_LEVEL | Log level: error, warn, info, debug | info | ❌ | | LOG_FILE | Log file path (logs to console if not set) | - | ❌ |

MCP Client Setup

Configure your MCP-compatible client to connect to this server. The configuration depends on your chosen transport method.

---

Transport Options

Standard I/O Transport (Default)

The default transport method uses standard input/output for communication. This is suitable for direct integration with AI systems that launch the server as a child process.

Example MCP Configuration:

{
  "mcpServers": {
    "mcp-confluence": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network=host",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_TOKEN",
        "ghcr.io/n11tech/mcp-confluence:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-confluence-server.com",
        "CONFLUENCE_TOKEN": "your_personal_access_token"
      }
    }
  }
}

HTTP Streaming Transport

For scenarios requiring remote connections or web-based integrations, the server supports HTTP streaming transport with Server-Sent Events (SSE).

Enable HTTP Transport:

# Using GHCR image
docker run -i --rm \
  -p 3003:3003 \
  -e CONFLUENCE_URL="https://your-confluence-server.com" \
  -e CONFLUENCE_TOKEN="your_personal_access_token" \
  -e ENABLE_HTTP_TRANSPORT="true" \
  -e MCP_HTTP_PORT="3003" \
  -e MCP_HTTP_ENDPOINT="/stream" \
  ghcr.io/n11tech/mcp-confluence:latest

# Using npm script
npm run start:http

Example MCP Configuration for HTTP Transport:

{
  "mcpServers": {
    "mcp-confluence": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "3003:3003",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_TOKEN",
        "-e", "ENABLE_HTTP_TRANSPORT",
        "-e", "MCP_HTTP_PORT",
        "-e", "MCP_HTTP_ENDPOINT",
        "ghcr.io/n11tech/mcp-confluence:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-confluence-server.com",
        "CONFLUENCE_TOKEN": "your_personal_access_token",
        "ENABLE_HTTP_TRANSPORT": "true",
        "MCP_HTTP_PORT": "3003",
        "MCP_HTTP_ENDPOINT": "/stream"
      }
    }
  }
}

HTTP Endpoints:

• POST http://localhost:3003/stream - Send MCP requests
• GET http://localhost:3003/stream - Server-Sent Events stream
• GET http://localhost:3003/health - Health check endpoint

---

Security

API Key Authentication

For HTTP transport, you can enable API key authentication to secure your server:

# Generate a secure API key (recommended: 32+ characters)
export MCP_API_KEY=$(openssl rand -hex 32)

# Run with authentication enabled
docker run -i --rm \
  -p 3003:3003 \
  -e CONFLUENCE_URL="https://your-confluence-server.com" \
  -e CONFLUENCE_TOKEN="your_personal_access_token" \
  -e ENABLE_HTTP_TRANSPORT="true" \
  -e MCP_API_KEY="your-secure-api-key-here" \
  mcp-confluence:latest

Configuration with API Key:

{
  "mcpServers": {
    "mcp-confluence": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "3003:3003",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_TOKEN",
        "-e", "ENABLE_HTTP_TRANSPORT",
        "-e", "MCP_API_KEY",
        "mcp-confluence:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-confluence-server.com",
        "CONFLUENCE_TOKEN": "your_personal_access_token",
        "ENABLE_HTTP_TRANSPORT": "true",
        "MCP_API_KEY": "your-secure-api-key-here"
      }
    }
  }
}

When API key authentication is enabled, all HTTP requests must include the API key in the request headers.

LLM Compatibility: Schema Sanitizer

Tool inputSchema payloads are normalized server-side to be compatible with stricter JSON Schema subsets used by LLM clients such as Google Gemini:

• JSON Schema unions expressed as type: ["string", "null"] are automatically rewritten to anyOf: [{type: "string"}, {type: "null"}]
• Anthropic Claude and OpenAI ChatGPT clients are unaffected (the rewritten form is semantically equivalent and natively supported)
• Prototype Pollution Defense: Sanitizer skips __proto__, prototype, and constructor keys
• Recursion Depth Cap: Bounded at depth 64 to prevent stack-overflow on hostile input
• Pure Transformation: Sanitizer never mutates caller input and performs no I/O

---

Available Tools

This server provides a comprehensive suite of tools for interacting with Confluence Server/Data Center:

Page Management

• confluence_get_page - Get content of a specific Confluence page by its ID, or by title and space key
• confluence_search - Search Confluence content using simple terms or CQL (Confluence Query Language)
• confluence_get_page_children - Get child pages and folders of a specific Confluence page
• confluence_get_page_history - Get version history of a Confluence page
• confluence_create_page - Create a new Confluence page
• confluence_update_page - Update an existing Confluence page
• confluence_delete_page - Delete an existing Confluence page
• confluence_move_page - Move a Confluence page under a different parent

Comments

• confluence_get_comments - Get comments for a specific Confluence page
• confluence_add_comment - Add a comment to a Confluence page
• confluence_reply_to_comment - Reply to an existing comment on a Confluence page

Labels

• confluence_get_labels - Get labels for a specific Confluence page
• confluence_add_label - Add a label to a Confluence page

Attachments

• confluence_get_attachments - Get attachments for a Confluence page
• confluence_download_attachment - Get metadata for a specific attachment on a Confluence page
• confluence_upload_attachment - Upload a single attachment to a Confluence page
• confluence_upload_attachments - Upload multiple attachments to a Confluence page
• confluence_delete_attachment - Delete an attachment from a Confluence page
• confluence_download_content_attachments - Get all attachments for a Confluence page
• confluence_get_page_images - Get image attachments for a Confluence page

Users & Analytics

• confluence_search_user - Search Confluence users using CQL
• confluence_get_page_views - Get analytics/view metadata for a Confluence page

---

Usage Examples

Page Operations

// Get a specific page by ID
await callTool('confluence_get_page', {
  page_id: '123456789'
});

// Search using CQL
await callTool('confluence_search', {
  query: 'type=page AND space=DEV AND text ~ "important concept"',
  limit: 20
});

// Create a new page
await callTool('confluence_create_page', {
  space_key: 'DEV',
  title: 'Architecture Decision Record',
  content: 'We decided to use the MCP protocol...'
});

// Update a page
await callTool('confluence_update_page', {
  page_id: '123456789',
  title: 'Updated Architecture Decision Record',
  content: 'Revised decision based on new requirements...'
});

Comment & Label Operations

// Add a comment
await callTool('confluence_add_comment', {
  page_id: '123456789',
  content: 'This looks great! Approved for publish.'
});

// Get page labels
await callTool('confluence_get_labels', {
  page_id: '123456789'
});

// Add a label
await callTool('confluence_add_label', {
  page_id: '123456789',
  name: 'documentation'
});

Attachment Operations

// Get page attachments
await callTool('confluence_get_attachments', {
  page_id: '123456789'
});

// Upload an attachment
await callTool('confluence_upload_attachment', {
  page_id: '123456789',
  file_path: '/path/to/diagram.png'
});

---

Development

Available Scripts

| Script | Description | |--------|-------------| | npm run build | Compile TypeScript to JavaScript | | npm start | Run the server with stdio transport | | npm run start:http | Run with HTTP streaming transport | | npm run dev | Watch mode for development | | npm run lint | Code quality checks | | npm run test | Run test suite | | npm run inspector | Debug MCP server interactions |

Architecture

The codebase follows clean architecture principles with dependency injection via InversifyJS:

src/
├── application/              # Application layer
│   ├── facade/               # Confluence client facades
│   ├── factory/              # MCP server factory interfaces
│   ├── use-case/             # Business logic (ConfluenceUseCase)
│   └── util/                 # Schema sanitizer, validators
├── domain/                   # Domain layer
│   ├── contracts/
│   │   ├── input/            # Input DTOs for all use cases
│   │   └── schemas/          # Zod validation schemas
│   └── gateway/              # Confluence client interfaces
│                             # (page, comment, label, attachment, user, analytic)
└── infrastructure/           # Infrastructure layer
    ├── client/               # Concrete Confluence API clients (Axios-based)
    ├── configuration/        # ConfluenceConfiguration, DI container, logger
    ├── factory/              # McpServerFactory
    └── http-streaming/       # HTTP/SSE transport implementation

Key design decisions:

• Clean Architecture: Strict layer separation — domain has no infrastructure dependencies
• Dependency Injection: InversifyJS container wires all dependencies at startup
• Schema Validation: All tool inputs are validated with Zod before use-case execution
• Dual Transport: Stdio (default) and HTTP streaming (SSE) supported side-by-side
• LLM Compatibility: Schema sanitizer normalizes tool schemas for Gemini/Claude/GPT compatibility

---

Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started, coding standards, and the pull request process.

For security vulnerabilities, please follow the responsible disclosure process described in [SECURITY.md](SECURITY.md).

---

License

This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.

---

Built with the Model Context Protocol

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: n11techhub
• Source: n11techhub/mcp-confluence
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.