Confluence MCP Server

一个用于 Confluence Server/Data Center 的 Model Context Protocol (MCP) Server，提供完整的知识库读写能力。

功能特性

• 搜索页面: 使用 CQL 查询语言搜索 Confluence 页面
• 读取页面: 获取页面详情，自动转换为 Markdown 格式
• 创建页面: 支持 Markdown 和原生格式创建新页面
• 更新页面: 更新现有页面的标题和内容
• 删除页面: 删除指定页面
• 空间管理: 列出空间、获取空间内容、获取子页面结构
• 格式转换: 支持 Confluence Storage Format 与 Markdown 互转

安装

pip install -e .

配置

创建 .env 文件或设置环境变量：

CONFLUENCE_BASE_URL=https://your-confluence-domain.com/confluence
CONFLUENCE_USERNAME=your-email@example.com
CONFLUENCE_API_TOKEN=your-api-token-or-password
CONFLUENCE_API_VERSION=latest
CONFLUENCE_TIMEOUT=30

使用

启动 MCP Server

confluence-mcp-server --url https://your-confluence/confluence --username user@example.com --api-token your-token

或使用环境变量：

source .env
confluence-mcp-server

命令行参数

confluence-mcp-server --help

Options:
  --url TEXT           Confluence base URL
  --username TEXT      Confluence username/email
  --api-token TEXT     Confluence API token or password
  --api-version TEXT   API version (default: latest)
  --timeout INTEGER    Request timeout in seconds
  -v, --version        Show the version and exit.
  --help               Show this message and exit.

支持的工具

内容操作

• search_pages: 使用 CQL 搜索页面
• get_page: 根据页面ID获取页面详情
• create_page: 创建新页面
• update_page: 更新现有页面
• delete_page: 删除页面
• get_page_by_title: 根据标题搜索页面

空间操作

• list_spaces: 列出所有空间
• get_space: 获取空间详情
• get_space_content: 获取空间中的内容列表
• get_child_pages: 获取父页面的子页面

CQL 查询示例

text ~ "用户登录" AND space = "TECH"
title ~ "API" AND type = "page"
space = "PRD" AND label = "2024"

多 Agent 使用教程

在 TRAE 中使用

方式一：通过项目技能导入（推荐）

1. 打开 TRAE IDE
2. 在项目面板中添加 confluence-skill 项目目录
3. TRAE 会自动识别 SKILL.md 和 mcp.json 配置
4. 在对话中直接使用自然语言触发技能

方式二：手动配置 MCP Server

1. 在终端启动 MCP Server：

cd /path/to/confluence-skill
source .venv/bin/activate
confluence-mcp-server

2. 在 TRAE 的设置中添加 MCP Server：
   • 名称: confluence-mcp-server
   • URL: http://localhost:8000

在 Cursor 中使用

1. 确保项目目录中有 .cursor/mcp.json 配置文件
2. Cursor 会自动读取配置并启动 MCP Server
3. 在对话中使用 @confluence-mcp-server 触发技能

.cursor/mcp.json 配置示例：

{
  "name": "confluence-mcp-server",
  "command": "python",
  "args": ["-m", "src.main"],
  "env": {
    "CONFLUENCE_BASE_URL": "${CONFLUENCE_BASE_URL}",
    "CONFLUENCE_USERNAME": "${CONFLUENCE_USERNAME}",
    "CONFLUENCE_API_TOKEN": "${CONFLUENCE_API_TOKEN}"
  },
  "description": "Confluence MCP Server for reading and writing Confluence pages"
}

在 Claude Code 中使用

方式一：通过 CLAUDE.md 配置

1. 在项目根目录创建或编辑 CLAUDE.md 文件
2. 添加以下配置：

---
skills:
  - name: confluence-skill
    type: mcp
    server:
      command: python
      args: ["-m", "src.main"]
      env:
        CONFLUENCE_BASE_URL: "${CONFLUENCE_BASE_URL}"
        CONFLUENCE_USERNAME: "${CONFLUENCE_USERNAME}"
        CONFLUENCE_API_TOKEN: "${CONFLUENCE_API_TOKEN}"
---

# Confluence 知识库技能

使用 Confluence 技能可以搜索、读取、创建和更新 Confluence 文档。

3. 在对话中直接使用自然语言触发：
   • "帮我搜索 Java 编码规范文档"
   • "获取页面 63777422 的内容"

方式二：手动启动 MCP Server

1. 启动 MCP Server：

cd /path/to/confluence-skill
source .venv/bin/activate
confluence-mcp-server

2. 在 Claude Code 设置中添加 MCP Server：
   • 打开 Claude Code 设置
   • 找到 MCP Servers 配置
   • 添加新服务器：http://localhost:8000

在 Codex 中使用

1. 在项目目录中创建 .codex/mcp.json 配置文件：

{
  "servers": [
    {
      "name": "confluence-mcp-server",
      "type": "http",
      "url": "http://localhost:8000",
      "description": "Confluence MCP Server"
    }
  ]
}

2. 启动 MCP Server：

cd /path/to/confluence-skill
source .venv/bin/activate
confluence-mcp-server

3. 在 Codex 对话中使用 @confluence-mcp-server 触发技能

在 OpenCode 中使用

1. 在项目目录中创建 .opencode/mcp.json 配置文件：

{
  "name": "confluence-mcp-server",
  "command": "python",
  "args": ["-m", "src.main"],
  "env": {
    "CONFLUENCE_BASE_URL": "${CONFLUENCE_BASE_URL}",
    "CONFLUENCE_USERNAME": "${CONFLUENCE_USERNAME}",
    "CONFLUENCE_API_TOKEN": "${CONFLUENCE_API_TOKEN}"
  },
  "description": "Confluence MCP Server for reading and writing Confluence pages"
}

2. OpenCode 会自动识别配置并启动 MCP Server
3. 在对话中使用 @confluence-mcp-server 触发技能

使用 MCP Python SDK

from mcp.stdio_client import StdioClient

async def main():
    async with StdioClient(command="python", args=["-m", "src.main"]) as client:
        # 搜索页面
        results = await client.call_tool("search_pages", {"cql": "text ~ 'Java'", "limit": 5})
        print(results)
        
        # 获取页面内容
        page = await client.call_tool("get_page", {"page_id": "63777422"})
        print(page.get("title"))
        print(page.get("body", {}).get("markdown"))
        
        # 创建页面
        new_page = await client.call_tool(
            "create_page",
            {
                "title": "新文档标题",
                "space_key": "TECH",
                "content": "# 新文档\n\n内容描述",
                "content_format": "markdown"
            }
        )
        print(new_page)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

使用 HTTP API

MCP Server 默认在 http://localhost:8000 提供 HTTP 接口。

列出所有工具

curl http://localhost:8000/mcp/list_tools

调用工具（POST）

curl -X POST http://localhost:8000/mcp/call_tool \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search_pages",
    "arguments": {
      "cql": "text ~ \"Java\"",
      "limit": 5
    }
  }'

在自定义 Agent 中集成

import requests

class ConfluenceSkillClient:
    def __init__(self, base_url="http://localhost:8000"):
        self.base_url = base_url
    
    def search_pages(self, cql, limit=20):
        return self._call_tool("search_pages", {"cql": cql, "limit": limit})
    
    def get_page(self, page_id):
        return self._call_tool("get_page", {"page_id": page_id})
    
    def create_page(self, title, space_key, content, content_format="markdown"):
        return self._call_tool(
            "create_page",
            {"title": title, "space_key": space_key, "content": content, "content_format": content_format}
        )
    
    def _call_tool(self, tool_name, arguments):
        response = requests.post(
            f"{self.base_url}/mcp/call_tool",
            json={"name": tool_name, "arguments": arguments}
        )
        return response.json()

client = ConfluenceSkillClient()
results = client.search_pages("text ~ '技术文档'")
print(results)

环境变量配置方式

方式一：使用 .env 文件

cp .env.example .env
# 编辑 .env 文件配置
source .env
confluence-mcp-server

方式二：命令行参数

confluence-mcp-server \
  --url https://docs.jk.com \
  --username zhengzih \
  --api-token your-password

方式三：系统环境变量

export CONFLUENCE_BASE_URL=https://docs.jk.com
export CONFLUENCE_USERNAME=zhengzih
export CONFLUENCE_API_TOKEN=your-password
confluence-mcp-server

技术栈

• Python 3.10+
• MCP SDK (mcp[cli])
• Requests
• BeautifulSoup4
• Markdown
• Click

许可证

MIT License