Confluence MCP 服务器

用于将 Atlassian Confluence 与 Claude Code 集成的模型上下文协议 (MCP) 服务器。

功能特性

• 🔍 搜索：使用 CQL (Confluence Query Language) 在 Confluence 页面中进行搜索

• 📄 读取：通过 ID 或标题读取页面

• ✏️ 创建与更新：创建和更新页面

• 🏷️ 管理标签：管理标签和元数据

• 📁 列出空间：列出空间和附件

• 🔐 安全：支持使用 API 令牌进行基本身份验证 (Basic Auth)

Related MCP server: mcp-confluence

安装

前置要求

• Node.js 18+ 和 npm

• Atlassian Confluence Cloud 账户

• API 令牌（见下文“配置”部分）

设置

git clone https://github.com/gkrauchunas-arlo/confluence-mcp.git
cd confluence-mcp
npm install

配置

1. 将 .env.example 复制为 .env：

   cp .env.example .env

2. 在 .env 中填入您的 Atlassian 凭据：

   ATLASSIAN_SITE=your-domain.atlassian.net
   ATLASSIAN_EMAIL=your-email@example.com
   ATLASSIAN_API_TOKEN=your-token

获取 API 令牌：

1. 访问 https://id.atlassian.com/manage-profile/security/api-tokens

2. 点击“创建 API 令牌” (Create API token)

3. 为其命名（例如“Claude Code MCP”），并将令牌复制到 .env 中

测试

# Test Confluence API connectivity
node test-confluence.js

# Test MCP protocol (via stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

连接到 Claude Code

选项 1：CLI（推荐）

claude mcp add --transport stdio confluence \
  --env ATLASSIAN_SITE="your-domain.atlassian.net" \
  --env ATLASSIAN_EMAIL="your-email@example.com" \
  --env ATLASSIAN_API_TOKEN="your-token" \
  -- node /absolute/path/to/confluence-mcp/index.js

将 /absolute/path/to/ 替换为您实际的安装路径（例如 /home/username/confluence-mcp）。

选项 2：配置文件

添加到您的 Claude Code MCP 配置文件中：

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["/absolute/path/to/confluence-mcp/index.js"],
      "env": {
        "ATLASSIAN_SITE": "your-domain.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "your-token"
      }
    }
  }
}

配置文件位置：

• Linux: ~/.config/claude-code/mcp_servers.json 或 ~/.claude/config/mcp_servers.json

• macOS: ~/Library/Application Support/claude-code/mcp_servers.json

• Windows: %APPDATA%\claude-code\mcp_servers.json

配置完成后，重启 Claude Code 以激活 MCP 服务器。

可用工具

搜索与导航

• confluence_search - 在所有内容中进行 CQL 搜索

  • 参数：query (字符串), limit (数字, 可选), spaceKey (字符串, 可选)

  • 示例：搜索特定空间内标题包含“API”的页面

• confluence_list_spaces - 列出所有空间

  • 参数：limit (数字, 可选, 默认: 25)

  • 返回：您的账户可访问的所有 Confluence 空间列表

读取内容

• confluence_get_page - 通过 ID 获取页面

  • 参数：pageId (字符串)

  • 返回：包含内容、版本和元数据的完整页面数据

• confluence_get_page_by_title - 通过标题和空间查找页面

  • 参数：title (字符串), spaceKey (字符串)

  • 返回：指定空间中标题完全匹配的页面

• confluence_get_space - 获取空间信息

  • 参数：spaceKey (字符串)

  • 返回：空间元数据和配置

• confluence_get_attachments - 列出页面附件

  • 参数：pageId (字符串)

  • 返回：页面上的所有附件列表

创建与编辑

• confluence_create_page - 创建新页面

  • 参数：title (字符串), spaceKey (字符串), content (HTML 字符串), parentId (字符串, 可选)

  • 在指定空间中创建新页面，可选作为另一个页面的子页面

• confluence_update_page - 更新现有页面

  • 参数：pageId (字符串), title (字符串), content (HTML 字符串), version (数字)

  • 使用新内容更新页面。版本号必须与当前页面版本匹配。

元数据

• confluence_add_labels - 为页面添加标签

  • 参数：pageId (字符串), labels (字符串数组)

  • 为页面添加一个或多个标签/标记以进行分类

使用示例

连接到 Claude Code 后，您可以使用自然语言与 Confluence 交互：

搜索页面

Find all pages about "API documentation" in Confluence

读取页面

Read the contents of Confluence page with ID 12345

创建新页面

Create a new page in the DEV space titled "API Guidelines" with this content:
<h1>API Guidelines</h1>
<p>This document describes our API design principles.</p>

更新页面

Update Confluence page 12345 to add a new section about authentication

添加标签

Add labels "documentation" and "api" to Confluence page 12345

CQL 查询示例

confluence_search 工具支持 Confluence 查询语言 (CQL)：

type=page AND title~"API"
type=page AND space=DEV
type=page ORDER BY lastmodified DESC
type=page AND label=documentation
type=page AND creator=currentUser()

API 参考

此 MCP 服务器使用 Confluence REST API：

• 基础 URL: https://{site}.atlassian.net/wiki/rest/api

• 身份验证: 使用电子邮件 + API 令牌进行基本身份验证

• API 版本: Cloud REST API (稳定版)

• 完整 API 文档

故障排除

“Authentication failed”（身份验证失败）

• 检查 .env 中的电子邮件和 API 令牌

• 确保令牌未过期（API 令牌不会过期，但可以被撤销）

• 确保您使用的是 API 令牌，而不是 Atlassian 账户密码

“MCP tools not showing up”（MCP 工具未显示）

• 完全重启 Claude Code（关闭并重新打开）

• 通过直接运行 node index.js 检查服务器日志以查找错误

• 使用 claude mcp list 验证配置

• 确保配置中使用了完整的绝对路径

“Permission denied”（权限被拒绝）错误

• 确保您的 Atlassian 账户有权访问请求的空间/页面

• 某些操作需要特定权限（例如，创建页面需要空间管理员权限）

• 在 Confluence Web UI 中检查空间权限

“Page version conflict”（页面版本冲突）

• 更新页面时，必须提供当前版本号

• 请先使用 confluence_get_page 获取当前版本

• 服务器将自动将版本号加 1

内容格式

Confluence 页面使用 存储格式 (Storage Format)（带有 Confluence 宏的 HTML）。对于简单页面，标准 HTML 即可：

<h1>Heading</h1>
<p>Paragraph with <strong>bold</strong> and <em>italic</em> text.</p>
<ul>
  <li>Bullet point 1</li>
  <li>Bullet point 2</li>
</ul>
<pre><code>Code block</code></pre>

有关高级功能，请参阅 Confluence 存储格式文档。

架构

基于以下技术构建：

• @modelcontextprotocol/sdk - MCP 协议实现

• axios - 用于 Confluence REST API 的 HTTP 客户端

• dotenv - 配置管理

该服务器作为基于 stdio 的 MCP 服务器运行，通过标准输入/输出使用 JSON-RPC 2.0 与 Claude Code 通信。

开发

项目结构

confluence-mcp/
├── index.js              # Main MCP server implementation
├── package.json          # Dependencies and scripts
├── test-confluence.js    # Confluence API connectivity tests
├── test-mcp.js           # MCP protocol tests (WIP)
├── .env.example          # Example configuration
├── .env                  # Your configuration (gitignored)
└── README.md             # This file

运行测试

# Test Confluence API directly
node test-confluence.js

# Test MCP server via stdio
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

贡献

欢迎贡献！请：

1. Fork 本仓库

2. 创建功能分支 (git checkout -b feature/amazing-feature)

3. 进行更改并编写测试

4. 提交更改 (git commit -m 'feat: add amazing feature')

5. 推送到分支 (git push origin feature/amazing-feature)

6. 提交 Pull Request

已知限制

1. 附件上传 - 尚未实现（需要 multipart/form-data 编码）

2. 富文本格式 - 仅支持基础 HTML，Confluence 宏可能很复杂

3. 分页 - 大量结果集受 limit 参数限制

4. 权限 - API 仅返回经过身份验证的用户可访问的内容

许可证

ISC

致谢

• 架构灵感来自 rovo-mcp

• 为 Claude Code 构建

• 使用了 模型上下文协议 (Model Context Protocol)

支持

• 问题反馈: https://github.com/gkrauchunas-arlo/confluence-mcp/issues

• Atlassian API 文档: https://developer.atlassian.com/cloud/confluence/rest/

• MCP 规范: https://modelcontextprotocol.io/specification

创建者: gkrauchunas-arlo 状态: 稳定版 v1.0.0 - 所有核心功能均已实现并经过测试