Content
# 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
```bash
# 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
```
2. **Build the Docker Image:**
```bash
docker build -t mcp-confluence:latest .
```
3. **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)
```bash
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
```
2. **Configure environment:**
```bash
cp config.template.env .env
# Edit .env with your Confluence credentials
```
3. **Build:**
```bash
npm run build
```
4. **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:**
```json
{
"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:**
```bash
# 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:**
```json
{
"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:
```bash
# 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:**
```json
{
"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
```javascript
// 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
```javascript
// 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
```javascript
// 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](https://modelcontextprotocol.io)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available