MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

C
Confluence MCP
by @JaniceWait
GitHub Repo(1 stars)

MCP server by JaniceWait

Created 10/14/2025
Updated 2 months ago
README
View Source
Repository documentation and setup instructions

Confluence MCP Server

Model Context Protocol (MCP) 服务器，用于 Atlassian Confluence

这是一个完整的 MCP 协议服务器实现，为 Confluence 提供全面的 REST API 访问能力。支持与 Cursor IDE、LLM 代理等 MCP 客户端集成。

✨ 功能特性

🔧 核心功能

  • 完整的 Confluence REST API 支持：覆盖所有主要 Confluence 操作
  • 双认证模式：支持 OAuth2 和 Basic Auth（API Token）
  • 双运行模式：Headless（服务器）和 GUI（桌面应用）
  • 跨平台：支持 Windows、macOS、Linux
  • Docker 支持：提供容器化部署方案

📋 支持的 Confluence 操作

内容管理

  • ✅ 搜索与检索（全文搜索、CQL 查询）
  • ✅ 创建、读取、更新、删除页面和博客
  • ✅ 移动内容到不同空间或父页面
  • ✅ 表格操作（读取和修改表格单元格）
  • ✅ 版本控制和历史管理

附件管理

  • ✅ 上传、下载、删除附件
  • ✅ 替换现有附件
  • ✅ 获取附件元数据

权限与安全

  • ✅ 查询内容权限
  • ✅ 添加/删除内容限制
  • ✅ 检查用户权限
  • ✅ 空间权限管理

空间管理

  • ✅ 创建、更新、删除空间
  • ✅ 获取空间信息和配置
  • ✅ 空间主页设置

协作功能

  • ✅ 标签管理（添加、删除、列表）
  • ✅ 评论管理（创建、更新、删除）
  • ✅ 用户信息查询
  • ✅ 用户组查询

高级功能

  • ✅ 内容属性（元数据）读写
  • ✅ 批量操作支持
  • ✅ 分享链接生成
  • ✅ 审计日志记录
  • ✅ 速率限制和重试机制

📦 安装

方式一：从源码安装

# 克隆仓库
git clone https://github.com/your-repo/confluence-mcp.git
cd confluence-mcp

# 安装依赖
pip install -r requirements.txt

# 安装包（开发模式）
pip install -e .

方式二：使用 pip（发布后）

# 基础安装（headless）
pip install confluence-mcp

# 包含 GUI
pip install confluence-mcp[gui]

# 完整安装（包含开发工具）
pip install confluence-mcp[all]

方式三：使用 Docker

# 拉取镜像
docker pull confluence-mcp:latest

# 或构建镜像
docker build -t confluence-mcp .

# 运行容器
docker-compose up -d

🚀 快速开始

Headless 模式（命令行/服务器）

  1. 创建配置文件
confluence-mcp config create -o config.yaml
  1. 编辑配置文件
confluence:
  url: "https://your-domain.atlassian.net"
  auth_method: "basic"
  basic:
    username: "your-email@example.com"
    password: "your-api-token"

mcp:
  host: "0.0.0.0"
  port: 8765
  api_key: "your-secure-api-key"
  1. 测试连接
confluence-mcp test -c config.yaml
  1. 启动服务器
confluence-mcp serve -c config.yaml

服务器将在 http://localhost:8765 启动。

GUI 模式（桌面应用）

  1. 启动 GUI
confluence-mcp-gui

  1. 配置界面

    • 在"配置"标签页填写 Confluence 服务器信息
    • 选择认证方式并输入凭证
    • 点击"测试连接"验证配置
    • 保存配置

  2. 启动服务器

    • 切换到"服务器"标签页
    • 点击"启动服务器"
    • 服务器状态显示为"运行中"

  3. 查看日志

    • 在"日志"标签页查看实时日志

🔌 与 Cursor 集成

配置 Cursor

  1. 启动 Confluence MCP 服务器（headless 或 GUI 模式）

  2. 在 Cursor 中配置 MCP 服务器：

方法一：通过 Cursor 设置界面

  • 打开 Cursor 设置
  • 找到 MCP Servers 配置
  • 添加新服务器

方法二：直接编辑配置文件

编辑 Cursor 的 MCP 配置文件（通常在 ~/.cursor/mcp_servers.json）：

{
  "mcpServers": {
    "confluence": {
      "name": "Confluence",
      "url": "http://localhost:8765",
      "apiKey": "your-secure-api-key",
      "enabled": true
    }
  }
}

在 Cursor 中使用

配置完成后，在 Cursor 中可以直接使用 AI 助手操作 Confluence：

# 示例对话

"搜索标题包含'API文档'的页面"
"在 DEV 空间创建一个新页面，标题是'测试页面'"
"获取页面 ID 12345 的内容"
"给页面添加标签：documentation, api"
"上传附件到页面 12345"

📚 API 文档

REST API 端点

启动服务器后，访问以下地址查看完整 API 文档：

  • OpenAPI/Swagger UI: http://localhost:8765/docs
  • ReDoc: http://localhost:8765/redoc

主要端点列表

| 端点 | 方法 | 说明 | |------|------|------| | /mcp/status | GET | 获取服务器状态 | | /mcp/auth/test | POST | 测试认证 | | /mcp/search | POST | 搜索内容 | | /mcp/content/get | POST | 获取内容 | | /mcp/content/create | POST | 创建内容 | | /mcp/content/update | POST | 更新内容 | | /mcp/content/delete | POST | 删除内容 | | /mcp/content/move | POST | 移动内容 | | /mcp/content/table/get | POST | 获取表格 | | /mcp/content/table/modify | POST | 修改表格 | | /mcp/attachments/add | POST | 添加附件 | | /mcp/attachments/get | POST | 获取附件 | | /mcp/attachments/delete | POST | 删除附件 | | /mcp/permissions/get | POST | 获取权限 | | /mcp/permissions/add | POST | 添加权限 | | /mcp/permissions/remove | POST | 删除权限 | | /mcp/space/create | POST | 创建空间 | | /mcp/space/get | POST | 获取空间 | | /mcp/labels/add | POST | 添加标签 | | /mcp/comments/add | POST | 添加评论 | | /mcp/batch/execute | POST | 批量操作 |

请求示例

搜索内容

curl -X POST http://localhost:8765/mcp/search \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "title~API",
    "space": "DEV",
    "limit": 10
  }'

创建页面

curl -X POST http://localhost:8765/mcp/content/create \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "space_key": "DEV",
    "title": "New Page",
    "body": "<p>This is a new page</p>",
    "content_type": "page"
  }'

上传附件

curl -X POST http://localhost:8765/mcp/attachments/add \
  -H "X-API-Key: your-api-key" \
  -F "content_id=123456" \
  -F "file=@/path/to/file.pdf" \
  -F "comment=Uploaded via MCP"

Python 客户端示例

import httpx

class ConfluenceMCPClient:
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url
        self.headers = {
            "X-API-Key": api_key,
            "Content-Type": "application/json"
        }
    
    async def search(self, query: str, space: str = None):
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/mcp/search",
                headers=self.headers,
                json={"query": query, "space": space}
            )
            return response.json()
    
    async def create_page(self, space_key: str, title: str, body: str):
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/mcp/content/create",
                headers=self.headers,
                json={
                    "space_key": space_key,
                    "title": title,
                    "body": body
                }
            )
            return response.json()

# 使用示例
import asyncio

async def main():
    client = ConfluenceMCPClient(
        base_url="http://localhost:8765",
        api_key="your-api-key"
    )
    
    # 搜索
    results = await client.search("title~API", space="DEV")
    print(results)
    
    # 创建页面
    page = await client.create_page(
        space_key="DEV",
        title="Test Page",
        body="<p>Hello World</p>"
    )
    print(page)

asyncio.run(main())

⚙️ 配置详解

配置文件格式

支持三种格式：YAML（推荐）、JSON、TOML

完整配置选项

# Confluence 服务器配置
confluence:
  url: "https://your-domain.atlassian.net"
  auth_method: "oauth2"  # 或 "basic"
  
  # OAuth2 配置（Cloud 推荐）
  oauth2:
    client_id: "your-client-id"
    client_secret: "your-client-secret"
    access_token: ""
    refresh_token: ""
  
  # Basic Auth 配置（API Token）
  basic:
    username: "your-email@example.com"
    password: "your-api-token"
  
  # 请求配置
  timeout: 30
  max_retries: 3
  retry_backoff: 2
  rate_limit_delay: 0.1
  
  # 代理配置
  proxy:
    enabled: false
    http: "http://proxy.example.com:8080"
    https: "https://proxy.example.com:8080"

# MCP 服务器配置
mcp:
  host: "0.0.0.0"
  port: 8765
  
  # 安全配置
  enable_tls: false
  tls_cert: "/path/to/cert.pem"
  tls_key: "/path/to/key.pem"
  api_key_enabled: true
  api_key: "your-secure-random-key"
  
  # CORS 配置
  cors_enabled: true
  cors_origins:
    - "http://localhost:*"
    - "https://cursor.sh"
  
  # 速率限制
  rate_limit_enabled: true
  rate_limit_requests: 100

# 日志配置
logging:
  level: "INFO"
  file_enabled: true
  file_path: "logs/confluence-mcp.log"
  audit_enabled: true
  audit_path: "logs/audit.log"

# 功能配置
features:
  batch_operations: true
  max_content_size: 10485760  # 10MB
  max_attachment_size: 52428800  # 50MB
  max_batch_size: 50
  cache_enabled: true
  cache_ttl: 300

环境变量覆盖

可以使用环境变量覆盖配置：

export CONFLUENCE__URL="https://your-domain.atlassian.net"
export CONFLUENCE__BASIC__USERNAME="your-email@example.com"
export CONFLUENCE__BASIC__PASSWORD="your-api-token"
export MCP__PORT="8765"
export MCP__API_KEY="your-api-key"

🔐 认证配置

Confluence Cloud (推荐 API Token)

  1. 生成 API Token

  2. 配置 Basic Auth

    confluence:
  url: "https://your-domain.atlassian.net"
  auth_method: "basic"
  basic:
    username: "your-email@example.com"
    password: "your-api-token"

Confluence Server (On-Premise)

使用用户名和密码：

confluence:
  url: "https://confluence.your-company.com"
  auth_method: "basic"
  basic:
    username: "your-username"
    password: "your-password"

OAuth 2.0 (高级)

  1. 在 Atlassian Developer Console 创建 OAuth 应用
  2. 配置回调 URL
  3. 获取 Client ID 和 Secret
  4. 配置：
confluence:
  auth_method: "oauth2"
  oauth2:
    client_id: "your-client-id"
    client_secret: "your-client-secret"

🐳 Docker 部署

使用 Docker Compose

  1. 创建配置目录
mkdir -p config logs
cp config.example.yaml config/config.yaml
# 编辑 config/config.yaml
  1. 编辑 docker-compose.yml
version: '3.8'

services:
  confluence-mcp:
    image: confluence-mcp:latest
    ports:
      - "8765:8765"
    volumes:
      - ./config:/app/config:ro
      - ./logs:/app/logs
    environment:
      - CONFLUENCE__URL=https://your-domain.atlassian.net
      - CONFLUENCE__BASIC__USERNAME=your-email@example.com
      - CONFLUENCE__BASIC__PASSWORD=your-api-token
      - MCP__API_KEY=your-secure-api-key
    restart: unless-stopped
  1. 启动服务
docker-compose up -d

单独运行 Docker

docker run -d \
  --name confluence-mcp \
  -p 8765:8765 \
  -v $(pwd)/config:/app/config:ro \
  -v $(pwd)/logs:/app/logs \
  -e CONFLUENCE__URL="https://your-domain.atlassian.net" \
  -e CONFLUENCE__BASIC__USERNAME="your-email@example.com" \
  -e CONFLUENCE__BASIC__PASSWORD="your-api-token" \
  -e MCP__API_KEY="your-api-key" \
  confluence-mcp:latest

📦 打包分发

Headless 包

chmod +x scripts/build_headless.sh
./scripts/build_headless.sh

生成：

  • dist/confluence-mcp-headless.tar.gz
  • dist/confluence-mcp-headless.zip
  • dist/*.whl (Python wheel)

GUI 包

chmod +x scripts/build_gui.sh
./scripts/build_gui.sh

生成：

  • dist/confluence-mcp-gui.tar.gz
  • dist/confluence-mcp-gui.zip
  • dist/confluence-mcp-gui.dmg (macOS)
  • dist/confluence-mcp-gui.exe (Windows，在 Windows 上构建)

Docker 镜像

chmod +x scripts/build_docker.sh
./scripts/build_docker.sh v1.0.0

🔒 安全最佳实践

  1. 保护 API Key

    • 使用强随机 API Key
    • 不要在代码中硬编码
    • 使用环境变量或密钥管理系统

  2. 使用 TLS

    • 生产环境启用 TLS
    • 使用有效的 SSL 证书

  3. 限制访问

    • 使用防火墙限制访问
    • 配置 CORS 白名单
    • 启用速率限制

  4. 审计日志

    • 启用审计日志
    • 定期检查日志
    • 考虑加密敏感日志

  5. 凭证存储

    • GUI 模式使用系统密钥环
    • Headless 模式使用环境变量
    • 不要将凭证提交到版本控制

🧪 开发与测试

运行测试

# 安装开发依赖
pip install -r requirements-dev.txt

# 运行所有测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=confluence_mcp --cov-report=html

# 运行特定测试
pytest tests/test_client.py

代码质量

# 代码格式化
black confluence_mcp/

# 代码检查
ruff check confluence_mcp/

# 类型检查
mypy confluence_mcp/

本地开发

# 开发模式安装
pip install -e .

# 启动服务器（自动重载）
confluence-mcp serve --config config.yaml --reload

📊 MCP 协议映射

| MCP Action | Confluence REST API | 说明 | |-----------|-------------------|------| | /mcp/search | GET /rest/api/content/search | CQL 搜索 | | /mcp/content/get | GET /rest/api/content/{id} | 获取内容 | | /mcp/content/create | POST /rest/api/content | 创建内容 | | /mcp/content/update | PUT /rest/api/content/{id} | 更新内容 | | /mcp/content/delete | DELETE /rest/api/content/{id} | 删除内容 | | /mcp/attachments/add | POST /rest/api/content/{id}/child/attachment | 添加附件 | | /mcp/permissions/add | POST /rest/api/content/{id}/restriction | 添加限制 | | /mcp/space/create | POST /rest/api/space | 创建空间 | | /mcp/labels/add | POST /rest/api/content/{id}/label | 添加标签 | | /mcp/comments/add | POST /rest/api/content | 创建评论 |

⚠️ 已知限制

  1. Confluence Cloud API 限制

    • 某些权限操作可能受限于 Cloud API
    • 批量操作有大小限制
    • 速率限制取决于 Confluence 套餐

  2. 表格操作

    • 仅支持简单的表格修改
    • 复杂表格结构可能需要手动处理

  3. Webhook 管理

    • 需要管理员权限
    • Cloud 和 Server 实现不同

🤝 贡献

欢迎贡献！请遵循以下步骤：

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🙏 致谢

📞 支持

注意：本项目是独立开发，非 Atlassian 官方产品。

Quick Setup
Installation guide for this server

Install Package (if required)

uvx confluence-mcp

Cursor configuration (mcp.json)

{ "mcpServers": { "janicewait-confluence-mcp": { "command": "uvx", "args": [ "confluence-mcp" ] } } }