Atlassian Confluence MCP Server

将 AI 连接到你的 Confluence 知识库

将 Claude、Cursor AI 和其他 AI 助手直接连接到你的 Confluence 空间、页面和文档，改变你访问和使用团队知识的方式。从知识库中即时获取答案，搜索所有空间，并简化文档工作流。

你可以做什么

• 向 AI 咨询文档内容：“我们的 API 身份验证流程是什么？”
• 搜索所有空间：“查找所有关于安全最佳实践的页面”
• 即时获取答案：“显示 Product 空间中最新的发行说明”
• 访问团队知识：“我们的远程办公 HR 政策是什么？”
• 查看页面评论：“显示架构文档上的讨论”
• 创建和更新内容：“在 DEV 空间中创建一个新页面”

适用人群

• 需要快速访问技术文档和 API 指南的开发者
• 搜索需求、规格和项目更新的产品经理
• 需要快速访问政策文档和员工资源的HR 团队
• 查找故障排除指南和知识库文章的支持团队
• 任何希望使用自然语言与 Confluence 交互的人

快速开始

只需 2 分钟即可开始使用：

1. 获取 Confluence 凭据

生成 Confluence API 令牌：

1. 前往 Atlassian API Tokens
2. 点击 Create API token
3. 为其命名，例如 “AI Assistant”
4. 立即复制生成的令牌（之后将无法再次查看！）

2. 立即试用

# Set your credentials
export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
export ATLASSIAN_USER_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your_api_token"

# List your Confluence spaces (TOON format by default)
npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

# Get details about a specific space with field filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces/123456" \
  --jq "{id: id, key: key, name: name, type: type}"

# Get a page with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages/789" \
  --jq "{id: id, title: title, status: status}"

# Search for pages (using CQL)
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/rest/api/search" \
  --query-params '{"cql": "type=page AND space=DEV"}'

连接到 AI 助手

Claude Desktop 用户

将以下内容添加到你的 Claude 配置文件（~/.claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-confluence"],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

重启 Claude Desktop 后，你将在状态栏中看到 confluence 服务。

其他 AI 助手

大多数 AI 助手都支持 MCP（Cursor AI、Continue.dev 等）。全局安装此服务：

npm install -g @aashari/mcp-server-atlassian-confluence

然后配置你的 AI 助手，使用 STDIO 传输方式调用 MCP 服务。全局安装后，可通过 mcp-atlassian-confluence 使用该二进制文件。

备选方案：配置文件

创建 ~/.mcp/configs.json 以进行系统范围的配置：

{
  "confluence": {
    "environments": {
      "ATLASSIAN_SITE_NAME": "your-company",
      "ATLASSIAN_USER_EMAIL": "[email protected]",
      "ATLASSIAN_API_TOKEN": "your_api_token"
    }
  }
}

**备选配置键：**系统还接受 "atlassian-confluence"、"@aashari/mcp-server-atlassian-confluence" 或 "mcp-server-atlassian-confluence"，可替代 "confluence"。

使用环境变量

你也可以使用环境变量或 .env 文件配置凭据：

# Create a .env file in your project directory
cat > .env << EOF
ATLASSIAN_SITE_NAME=your-company
[email protected]
ATLASSIAN_API_TOKEN=your_api_token
DEBUG=false
EOF

服务会按以下顺序自动加载这些值：

1. 环境变量
2. 当前目录中的 .env 文件
3. ~/.mcp/configs.json（如上所示）

可用工具

此 MCP 服务提供 5 个通用工具，可访问任意 Confluence API 端点：

工具	描述
conf_get	对任意 Confluence API 端点执行 GET（读取数据）
conf_post	对任意端点执行 POST（创建资源）
conf_put	对任意端点执行 PUT（替换资源）
conf_patch	对任意端点执行 PATCH（部分更新）
conf_delete	对任意端点执行 DELETE（移除资源）

工具参数

所有工具共用以下参数：

• path（必填）：API 端点路径（例如，/wiki/api/v2/spaces）
• queryParams（可选）：以键值对形式提供的查询参数（例如，{"limit": "25", "space-id": "123"}）
• jq（可选）：用于筛选或转换响应的 JMESPath 表达式（例如，results[*].{id: id, title: title}）
• outputFormat（可选）：输出格式——"toon"（默认，令牌数减少 30-60%）或 "json"

接受请求正文的工具（conf_post、conf_put、conf_patch）：

• body（必填）：作为 JSON 对象的请求正文

常见 API 路径

空间：

• /wiki/api/v2/spaces - 列出所有空间
• /wiki/api/v2/spaces/{id} - 获取空间详情

页面：

• /wiki/api/v2/pages - 列出页面（使用 space-id 查询参数进行筛选）
• /wiki/api/v2/pages/{id} - 获取页面详情
• /wiki/api/v2/pages/{id}/body - 获取页面正文（使用 body-format 参数）
• /wiki/api/v2/pages/{id}/children - 获取子页面
• /wiki/api/v2/pages/{id}/labels - 获取页面标签

评论：

• /wiki/api/v2/pages/{id}/footer-comments - 列出／添加页脚评论
• /wiki/api/v2/pages/{id}/inline-comments - 列出／添加行内评论
• /wiki/api/v2/footer-comments/{comment-id} - 获取／更新／删除评论

博客文章：

• /wiki/api/v2/blogposts - 列出博客文章
• /wiki/api/v2/blogposts/{id} - 获取博客文章

搜索：

• /wiki/rest/api/search - 搜索内容（使用 cql 查询参数）

TOON 输出格式

什么是 TOON？ TOON（面向令牌的对象表示法）是一种针对大模型令牌效率优化的格式，与 JSON 相比可降低 30-60% 的令牌成本。它是所有工具的默认输出格式。

优点：

• 表格数组比 JSON 数组使用更少的令牌
• 语法开销极小（不必要时无需引号、括号和逗号）
• 仍然易于阅读和解析

何时改用 JSON：

• 需要为其他工具提供标准 JSON 时
• 需要调试或手动检查时

示例对比：

// JSON format (verbose)
{"results": [{"id": "123", "title": "My Page"}, {"id": "456", "title": "Other Page"}]}

// TOON format (efficient)
results:
  - id: 123
    title: My Page
  - id: 456
    title: Other Page

若要使用 JSON 而非 TOON，请在请求中设置 outputFormat: "json"。

JMESPath 筛选

所有工具都支持可选的 JMESPath（jq）筛选，用于提取特定数据并降低令牌成本：

# Get just space names and keys
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --jq "results[].{id: id, key: key, name: name}"

# Get page title and status
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages/123456" \
  --jq "{id: id, title: title, status: status}"

重要提示： 始终使用 jq 参数，将响应筛选为仅包含所需字段。未经筛选的响应可能非常庞大，令牌成本也很高。

JMESPath 语法参考：

• 官方文档：jmespath.org
• 常见模式：
  • results[*] - results 数组中的所有项目
  • results[0] - 仅第一个项目
  • results[*].id - 所有项目的 ID
  • results[*].{id: id, title: title} - 创建仅包含所选字段的对象
  • results[?status=='current'] - 按条件筛选

实际示例

探索知识库

向 AI 助手提问：

• “列出我们 Confluence 中的所有空间”
• “显示 Engineering 空间的详细信息”
• “我们的 Product 空间里有哪些页面？”
• “查找 Marketing 空间中最新的页面”

搜索和查找信息

向 AI 助手提问：

• “搜索有关 API 身份验证的页面”
• “查找标题中包含 ‘security’ 的所有文档”
• “显示带有 ‘getting-started’ 标签的页面”
• “搜索 DEV 空间中有关部署的内容”

访问特定内容

向 AI 助手提问：

• “获取 API Authentication Guide 页面的内容”
• “显示入职清单文档”
• “我们的安全策略页面里有什么？”
• “显示最新的发行说明”

创建和更新内容

向 AI 助手提问：

• “在 DEV 空间中创建一个标题为 ‘API Guide’ 的新页面”
• “在架构文档中添加评论”
• “用新的发行信息更新页面内容”

CLI 命令

CLI 为 MCP 工具提供对应命令，方便直接在终端中访问。所有命令均支持与工具相同的参数。

可用命令

• get - 对任意 Confluence 端点执行 GET 请求
• post - 对任意端点执行 POST 请求
• put - 对任意端点执行 PUT 请求
• patch - 对任意端点执行 PATCH 请求
• delete - 从任意端点执行 DELETE 请求

CLI 参数

所有命令：

• -p, --path <path>（必需）- API 端点路径
• -q, --query-params <json>（可选）- 以 JSON 格式提供的查询参数
• --jq <expression>（可选）- JMESPath 筛选表达式
• -o, --output-format <format>（可选）- 输出格式：toon（默认）或 json

带请求正文的命令（post、put、patch）：

• -b, --body <json>（必需）- 以 JSON 格式提供的请求正文

示例

# GET request
npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

# GET with query parameters and JMESPath filter
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages" \
  --query-params '{"space-id": "123456", "limit": "10"}' \
  --jq "results[*].{id: id, title: title}"

# GET with JSON output format
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --output-format json

# POST request (create a page)
npx -y @aashari/mcp-server-atlassian-confluence post \
  --path "/wiki/api/v2/pages" \
  --body '{"spaceId": "123456", "status": "current", "title": "New Page", "body": {"representation": "storage", "value": "<p>Content here</p>"}}'

# POST request (add a comment)
npx -y @aashari/mcp-server-atlassian-confluence post \
  --path "/wiki/api/v2/pages/789/footer-comments" \
  --body '{"body": {"representation": "storage", "value": "<p>My comment</p>"}}'

# PUT request (update page - requires version increment)
npx -y @aashari/mcp-server-atlassian-confluence put \
  --path "/wiki/api/v2/pages/789" \
  --body '{"id": "789", "status": "current", "title": "Updated Title", "spaceId": "123456", "body": {"representation": "storage", "value": "<p>Updated content</p>"}, "version": {"number": 2}}'

# PATCH request (partial update)
npx -y @aashari/mcp-server-atlassian-confluence patch \
  --path "/wiki/api/v2/spaces/123456" \
  --body '{"name": "New Space Name"}'

# DELETE request
npx -y @aashari/mcp-server-atlassian-confluence delete \
  --path "/wiki/api/v2/pages/789"

响应处理

大型响应截断

当 API 响应超过约 40,000 个字符（约 10,000 个 token）时，服务器会自动截断响应，以确保不超出 token 限制。发生这种情况时：

1. 你会在响应末尾看到截断提示，其中显示：

   • 已显示的原始响应内容量
   • 原始响应大小
   • 如何访问完整数据的指引

2. 完整的原始响应会保存到 /tmp/mcp/ 中的临时文件（路径会在截断提示中提供）

3. 避免截断的最佳做法：

   • 始终使用 jq 参数，将响应筛选为仅包含所需字段
   • 使用 limit 查询参数限制结果数量（例如，{"limit": "5"}）
   • 按 ID 请求特定资源，而不要列出所有资源
   • 搜索时使用有针对性的 CQL 查询

高效筛选示例：

# Instead of getting all space data (can be huge):
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces"

# Get only the fields you need:
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --query-params '{"limit": "10"}' \
  --jq "results[*].{id: id, key: key, name: name}"

调试日志

启用调试日志以查看详细的请求／响应信息：

# Set DEBUG environment variable
export DEBUG=true

# For MCP mode
DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence

# For CLI mode
DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

调试日志写入位置：~/.mcp/data/@aashari-mcp-server-atlassian-confluence.[session-id].log

测试与开发

使用 MCP Inspector

MCP Inspector 提供了一个可视化界面，用于测试工具：

# Install the server globally
npm install -g @aashari/mcp-server-atlassian-confluence

# Run with MCP Inspector
npx @modelcontextprotocol/inspector node $(which mcp-atlassian-confluence)

如果你已克隆该仓库，也可以使用内置的开发命令：

npm run mcp:inspect

这会以 HTTP 模式启动服务，并在浏览器中打开 Inspector UI。

使用 HTTP 模式进行测试

你可以在 HTTP 模式下运行服务，以便使用 curl 或其他 HTTP 客户端进行测试：

# Start server in HTTP mode
TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence

服务默认会监听 http://localhost:3000/mcp。你可以更改端口：

PORT=8080 TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence

使用 curl 进行测试：

# Initialize session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "clientInfo": {"name": "curl-test", "version": "1.0.0"}, "capabilities": {}}}'

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Call a tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "conf_get", "arguments": {"path": "/wiki/api/v2/spaces", "queryParams": {"limit": "5"}}}}'

响应以服务器发送事件（SSE）形式返回，格式如下：

event: message
data: {"jsonrpc": "2.0", "id": 1, "result": {...}}

故障排除

“Authentication failed”或“403 Forbidden”

1. 检查你的 API Token 权限：

   • 前往 Atlassian API Tokens
   • 确保你的 token 仍处于有效状态且尚未过期

2. 检查站点名称格式：

   • 如果你的 Confluence URL 是 https://mycompany.atlassian.net
   • 站点名称应仅为 mycompany

3. 测试你的凭据：

   npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces?limit=1"
   

“Resource not found”或“404”

1. 检查 API 路径：

   • 路径区分大小写
   • 空间和页面请使用数字 ID（而非 key）
   • 在浏览器中确认资源是否存在

2. 检查访问权限：

   • 确保你能在浏览器中访问该空间／页面
   • 某些内容可能仅对特定用户开放

搜索时显示“No results found”

1. 尝试不同的搜索词：

   • 使用 CQL 语法进行高级搜索
   • 尝试范围更广的搜索条件

2. 检查 CQL 语法：

   • 先在 Confluence 的高级搜索中验证你的 CQL

Claude Desktop 集成问题

1. 更新配置文件后，重启 Claude Desktop
2. 确认配置文件位置：
   • macOS：~/.claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

获取帮助

如果问题仍未解决：

1. 运行简单的测试命令，确认一切正常
2. 查看 GitHub Issues，了解是否有类似问题
3. 创建新 issue，并附上错误消息和环境详情

常见问题

我需要哪些权限？

你的 Atlassian 账户需要：

• Confluence 访问权限，并具备查询所需空间的相应权限
• API token，并具备相应权限（创建 token 时会自动授予）

我可以将其用于 Confluence Server（本地部署）吗？

目前，此工具仅支持 Confluence Cloud。未来版本可能会添加对 Confluence Server/Data Center 的支持。

如何找到我的站点名称？

站点名称是 Confluence URL 的第一部分：

• URL：https://mycompany.atlassian.net -> 站点名称：mycompany
• URL：https://acme-corp.atlassian.net -> 站点名称：acme-corp

该工具适用于哪些 AI 助手？

适用于所有支持 Model Context Protocol（MCP）的 AI 助手：

• Claude Desktop
• Cursor AI
• Continue.dev
• 许多其他助手

我的数据安全吗？

是的！此工具：

• 完全在你的本地计算机上运行
• 使用你自己的 Confluence 凭据
• 绝不会将你的数据发送给第三方
• 只访问你授权访问的内容

我可以一次搜索所有空间吗？

可以！使用 CQL 查询跨空间搜索。例如：

npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/rest/api/search" \
  --query-params '{"cql": "type=page AND text~\"API documentation\""}'

从 v2.x 迁移

3.0 版用 5 个通用 HTTP 方法工具取代了 8 个以上的专用工具。如果你要从 v2.x 升级：

之前（v2.x）：

conf_ls_spaces, conf_get_space, conf_ls_pages, conf_get_page,
conf_search, conf_ls_comments, conf_add_comment, ...

之后（v3.0）：

conf_get, conf_post, conf_put, conf_patch, conf_delete

迁移示例：

• conf_ls_spaces -> 使用路径 /wiki/api/v2/spaces 调用 conf_get
• conf_get_space -> 使用路径 /wiki/api/v2/spaces/{id} 调用 conf_get
• conf_ls_pages -> 使用路径 /wiki/api/v2/pages?space-id={id} 调用 conf_get
• conf_get_page -> 使用路径 /wiki/api/v2/pages/{id} 调用 conf_get
• conf_search -> 使用路径 /wiki/rest/api/search?cql=... 调用 conf_get
• conf_add_comment -> 使用路径 /wiki/api/v2/pages/{id}/footer-comments 调用 conf_post

技术详情

要求

• Node.js：18.0.0 或更高版本
• MCP SDK：1.23.0（使用现代 registerTool API）
• Confluence：仅支持 Cloud（不支持 Server/Data Center）

架构

此服务采用 5 层架构：

1. 工具层（src/tools/）- 使用 Zod 验证的 MCP 工具定义
2. CLI 层（src/cli/）- 基于 Commander 的 CLI，可用于直接测试
3. 控制器层（src/controllers/）- 业务逻辑、JMESPath 过滤和输出格式化
4. 服务层（src/services/）- 与 Confluence API 通信
5. 实用工具层（src/utils/）- 共享实用工具（日志记录器、配置、格式化器、TOON 编码器）

功能

• 通用 HTTP 方法工具 - 访问任意 Confluence API 端点
• TOON 输出格式 - 与 JSON 相比减少 30%–60% 的令牌消耗
• JMESPath 过滤 - 仅提取所需数据
• 响应截断 - 自动处理大型响应
• 原始响应日志 - 完整响应保存到 /tmp/mcp/
• 双传输方式 - STDIO（用于 Claude Desktop）和 HTTP（用于 Web 集成）
• 调试日志 - 提供全面的日志以便排查问题

版本历史

v3.2.1（当前版本）

• 添加原始响应日志功能，并截断大型 API 响应
• 改进依赖项兼容性

v3.2.0

• 将 MCP SDK 升级至 v1.23.0，并采用 registerTool API

v3.1.0

• 添加 TOON 输出格式，以减少大模型响应的令牌消耗

v3.0.0（重大变更）

• 用 5 个通用 HTTP 方法工具取代 8 个以上的领域专用工具
• 添加 JMESPath 过滤支持
• 通过通用方法全面访问 Confluence API

完整版本历史请参见 CHANGELOG.md。

支持

需要帮助？以下是获取帮助的方式：

1. 查看上方的故障排除部分 - 其中涵盖了大多数常见问题
2. 访问我们的 GitHub 仓库，查看文档和示例：github.com/aashari/mcp-server-atlassian-confluence
3. 在 GitHub Issues 报告问题
4. 发起讨论，提出功能请求或一般性问题

---

用心打造，献给希望将 AI 融入知识管理工作流的团队。