Confluence MCP Server

基于模型上下文协议（MCP）的Confluence集成服务器，允许AI助手通过标准化接口查询和管理Confluence页面内容。

功能

• 🔍 CQL搜索 -使用Confluence查询语言搜索页面
• 📄 页面内容检索 -检索指定页面的完整内容
• ✏️ 页面内容更新 -修改Confluence页面的内容
• 📊 智能表格解析 -自动将HTML表格解析为结构化的JSON数据
• 🔐 多种认证方法 -支持个人令牌和个人邮箱加API密钥认证

安装

预备条件

• Node.js 16+
• Npm 或 yarn
• Confluence账户及访问权限

安装步骤

# 克隆或下载项目
cd confluence-mcp-server

# 安装依赖
npm install

# 编译 TypeScript
npm run build

配置

环境变量

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

# Confluence实例URL
CONFLUENCE_URL=https://your-domain.atlassian.net/wiki

# 认证方式 1: 个人访问令牌（推荐）
CONFLUENCE_PERSONAL_TOKEN=your_personal_token_here

# 认证方式 2: 邮箱 + API密钥
CONFLUENCE_API_MAIL=your-email@example.com
CONFLUENCE_API_KEY=your_api_key_here

获取认证凭证

个人访问令牌（推荐）

1. 登录Confluence
2. 进入设置 → 个人访问令牌
3. 点击创建令牌
4. 复制生成的令牌

API密钥（传统方法）

1. 登录Atlassian账户
2. 进入API令牌
3. 点击创建API令牌
4. 使用电子邮件和API密钥进行认证

在Claude Desktop中配置

编辑Claude Desktop配置文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["D:\\confluence-mcp-server\\build\\index.js"],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_PERSONAL_TOKEN": "your_token_here"
      }
    }
  }
}

可用工具

1. execute_cql_search

使用CQL搜索Confluence页面。

参数

• cql (必填): CQL查询字符串
• limit (选填): 返回结果的数量，默认为10

示例:

{
  "cql": "type=page and space=DEV and title~\"API\"",
  "limit": 5
}

返回格式:

{
  "size": 5,
  "limit":  5,
  "results": [
    {
      "id": "123456",
      "type": "page",
      "status": "current",
      "title": "API 文档",
      "space": "DEV",
      "version": 12,
      "lastModified": "2025-01-15T10:30:00.000+08:00",
      "url": "https://your-domain.atlassian.net/wiki/pages/viewpage.action?pageId=123456"
    }
  ]
}

2. get_page_content

检索指定页面的内容，并自动解析表格数据。

参数

• pageId (必填): Confluence页面ID

示例:

{
  "pageId": "123456"
}

返回格式（包括表格）:

{
  "id": "123456",
  "type": "page",
  "status": "current",
  "title": "模块接口文档",
  "space": {
    "key": "DEV",
    "name": "开发团队"
  },
  "version": {
    "number": 15,
    "when": "2025-01-15T10:30:00.000+08:00",
    "by": "张三"
  },
  "url": "https://...",
  "tables": [
    {
      "headers": ["功能名称", "负责人", "状态"],
      "rows": [
        {
          "功能名称": "用户认证",
          "负责人": "张三",
          "状态": "完成"
        },
        {
          "功能名称": "数据同步",
          "负责人": "李四",
          "状态": "进行中"
        }
      ]
    }
  ]
}

返回格式（无表格）:

{
  "id": "123456",
  "title": "普通文档",
  "content": "<p>原始 HTML 内容...</p>"
}

3. update_page_content

更新Confluence页面内容。

参数

• pageId (必填): 页面ID
• content (必填): 新内容，HTML格式
• title (选填): 新标题

示例:

{
  "pageId": "123456",
  "content": "<p>更新后的内容</p>",
  "title": "新标题（可选）"
}

CQL查询示例

-- 搜索特定空间的页面
type=page and space=DEV

-- 按标题模糊搜索
type=page and title~"接口文档"

-- 搜索最近修改的页面
type=page and lastModified >= "2025-01-01"

-- 搜索特定作者创建的页面
type=page and creator="username"

-- 组合查询
type=page and space=DEV and title~"API" and lastModified >= "2025-01-01"

更多CQL语法，请参阅Confluence CQL文档。

开发与测试

运行测试

# 测试连接
node test-connection.js

# 测试页面访问
node test-page-access.js

# 测试优化后的输出
node test-parsed-output.js

开发模式

# 监视文件变化并自动编译
npm run watch

# 使用 MCP Inspector 调试
npm run inspector

项目结构

confluence-mcp-server/
├── src/
│   └── index.ts           # 主服务器代码
├── build/                 # 编译后的 JavaScript
├── test-connection.js     # 连接测试脚本
├── test-page-access.js    # 页面访问测试
├── test-parsed-output.js  # 输出优化测试
├── package.json
├── tsconfig.json
└── README.md

数据优化

此服务器对Confluence API返回的数据进行了如下优化：

1. 移除冗余字段 -过滤掉_expandable、_links等内部元数据
2. 智能表格解析 -自动将HTML表格提取为结构化的JSON
3. 清理HTML标签 -移除Confluence特有的标签如<ac:task-list>、<ac:link>
4. 简化版本信息 -仅保留关键版本和作者信息

故障排除

认证失败

• 确认环境变量设置正确
• 检查Token或API密钥是否有效
• 确认账户有权访问目标页面

无法检索页面内容

• 确认页面ID正确
• 检查页面是否已被删除或归档
• 确认有读取权限

表格解析不完整

• 检查HTML结构是否符合标准
• 一些复杂的表格可能需要手动处理
• 查看原始content字段调试

许可证

MIT许可证

贡献

欢迎提交Issue和Pull Requests！

相关资源

• 模型上下文协议
• Confluence REST API
• Confluence CQL