Name: Confluence知识库AI连接服务
Author: aashari

使用说明

将AI连接到您的汇流知识库

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

你能做什么

向AI询问您的文档：“我们的API身份验证过程是什么？”
在所有空间中搜索：“查找有关安全最佳实践的所有页面”
获得即时答案：“显示产品空间的最新发行说明”
获取团队知识：“我们对远程工作的人力资源政策是什么？”
查看页面评论：“向我展示架构文档的讨论”
创建和更新内容：“在开发空间中创建新页面”

非常适合

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

快速开始

2分钟后起床跑步：

1.获取您的Confluence凭据

生成Confluence API令牌：

首选大西洋API代币
点击 创建API令牌
给它起个名字，比如 “AI助手”
复制生成的令牌 立即（你不会再看到它了！）

2.立即尝试

# Set your credentials
export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
export ATLASSIAN_USER_EMAIL="your.email@company.com"
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桌面用户

将其添加到您的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": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

重新启动Claude Desktop，您将在状态栏中看到汇流服务器。

其他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": "your.email@company.com",
      "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
ATLASSIAN_USER_EMAIL=your.email@company.com
ATLASSIAN_API_TOKEN=your_api_token
DEBUG=false
EOF

服务器将自动从以下位置加载这些值：

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

可用工具

此MCP服务器提供5种通用工具，可以访问任何Confluence API端点：

工具	说明
`conf_get`	获取任何Confluence API端点（读取数据）
`conf_post`	POST到任何端点（创建资源）
`conf_put`	PUT到任何端点（替换资源）
`conf_patch`	连接到任何端点（部分更新）
`conf_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（面向令牌的对象表示法）是一种针对LLM令牌效率进行优化的格式，与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[0] -仅第一项
- results[*].id -仅显示所有项目的ID
- results[*].{id: id, title: title} -使用选定字段创建对象
- results[?status=='current'] -按条件筛选

真实世界的例子

探索您的知识库

问你的AI助手：

“列出我们Confluence中的所有空间”
“显示工程空间的详细信息”
“我们的产品空间中有哪些页面？”
“查找营销空间中的最新页面”

搜索和查找信息

问你的AI助手：

“搜索有关API身份验证的页面”
“查找标题中带有“安全性”的所有文档”
“显示标有“开始”的页面”
“在DEV空间中搜索有关部署的内容”

访问特定内容

问你的AI助手：

“获取API身份验证指南页面的内容”
“给我看入职检查表文件”
“我们的安全政策页面上有什么？”
“显示最新发行说明”

创建和更新内容

问你的AI助手：

“在DEV空间中创建标题为“API指南”的新页面”
“在架构文档中添加注释”
“用新的发布信息更新页面内容”

CLI命令

CLI镜像MCP工具，用于直接终端访问。所有命令都支持与工具相同的参数。

可用命令

get -获取任何Confluence端点
post -POST到任何端点
put -PUT到任何端点
patch -点击任何端点
delete -从任何端点删除

CLI参数

所有命令：

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

带有body的命令（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响应超过约40000个字符（约10000个令牌）时，服务器会自动截断响应以保持在令牌限制内。当这种情况发生时：

你会看到一个截断通知 在响应的末尾显示：
- 显示了多少原始响应
- 原始响应大小
- 获取完整数据的指南
完整的原始响应已保存 到中的临时文件 /tmp/mcp/ （截断通知中提供的路径）
避免截断的最佳实践：
- 始终使用 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检查器

MCP检查器为测试工具提供了一个可视化界面：

# 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模式启动服务器，并在浏览器中打开检查器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

卷曲测试：

# 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": {...}}

故障排除

“身份验证失败”或“403禁止”

检查您的API代币权限:
- 首选大西洋API代币
- 确保您的令牌仍然有效且未过期
验证您的网站名称格式:
- 如果你的Confluence URL是 https://mycompany.atlassian.net
- 您的网站名称应该只是 mycompany

测试您的凭据:

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

“找不到资源”或“404”

检查API路径:
- 路径区分大小写
- 对空格和页面使用数字ID（而不是键）
- 验证浏览器中是否存在该资源
验证访问权限:
- 确保您可以访问浏览器中的空间/页面
- 某些内容可能仅限于某些用户

搜索时“未找到结果”

尝试不同的搜索词:
- 使用CQL语法进行高级搜索
- 尝试更广泛的搜索条件
检查CQL语法:
- 首先在Confluence的高级搜索中验证您的CQL

Claude桌面集成问题

重新启动克劳德桌面 更新配置文件后
验证配置文件位置:
- macOS： ~/.claude/claude_desktop_config.json
- 窗户： %APPDATA%\Claude\claude_desktop_config.json

获取帮助

如果你仍然有问题：

运行一个简单的测试命令来验证一切正常
检查 GitHub问题对于类似的问题
使用错误消息和设置详细信息创建新问题

常见问题

我需要什么权限？

您的Atlassian帐户需要：

接入汇流 具有要查询的空间的适当权限
API令牌 具有适当的权限（创建权限时自动授予）

我可以将其与Confluence服务器（内部部署）一起使用吗？

目前，该工具仅支持 汇流云。未来版本中可能会添加对Confluence服务器/数据中心的支持。

我如何找到我的网站名称？

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

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

这与哪些AI助手一起工作？

任何支持模型上下文协议（MCP）的AI助手：

克劳德桌面版
光标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 -> conf_get 与路径 /wiki/api/v2/spaces
conf_get_space -> conf_get 与路径 /wiki/api/v2/spaces/{id}
conf_ls_pages -> conf_get 与路径 /wiki/api/v2/pages?space-id={id}
conf_get_page -> conf_get 与路径 /wiki/api/v2/pages/{id}
conf_search -> conf_get 与路径 /wiki/rest/api/search?cql=...
conf_add_comment -> conf_post 与路径 /wiki/api/v2/pages/{id}/footer-comments

技术细节

需求

Node.js：18.0.0或更高
MCP-SDK：1.23.0（使用现代 registerTool API
汇流：仅限云（不支持服务器/数据中心）

建筑

此服务器遵循5层架构：

工具层 (src/tools/)-带Zod验证的MCP工具定义
CLI层 (src/cli/)-基于命令行界面的直接测试
控制器层 (src/controllers/)-业务逻辑、JMESPath过滤、输出格式化
服务层 (src/services/)-汇流API通信
Utils图层 (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版本

使用registerTool API将MCP SDK现代化到v1.23.0

v3.1.0

为令牌高效的LLM响应添加TOON输出格式

v3.0.0 （突变）

用5个通用HTTP方法工具替换8个以上特定于域的工具
添加JMESPath过滤支持
通过通用方法完全访问Confluence API

看更改日志.md 查看完整的版本历史记录。

支持

需要帮助？以下是如何获得帮助：

检查上面的故障排除部分 -其中涵盖了最常见的问题
访问我们的GitHub仓库 有关文档和示例： github/aashari/mcp服务器-大西洋影响
报告问题 在 GitHub问题
开始讨论 用于功能请求或一般问题

为希望将人工智能引入知识管理工作流程的团队精心打造。

使用说明

将AI连接到您的汇流知识库

你能做什么

非常适合

快速开始

1.获取您的Confluence凭据

2.立即尝试

连接到AI助手

适用于Claude桌面用户

其他AI助理

替代方案：配置文件

使用环境变量

可用工具

刀具参数

常见的API路径

TOON输出格式

JMESPath过滤

真实世界的例子

探索您的知识库

搜索和查找信息

访问特定内容

创建和更新内容

CLI命令

可用命令

CLI参数

例子

响应处理

大响应截断

调试日志记录

测试与开发

使用MCP检查器

HTTP测试模式

故障排除

“身份验证失败”或“403禁止”

“找不到资源”或“404”

搜索时“未找到结果”

Claude桌面集成问题

获取帮助

常见问题

我需要什么权限？

我可以将其与Confluence服务器（内部部署）一起使用吗？

我如何找到我的网站名称？

这与哪些AI助手一起工作？

我的数据安全吗？

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

从v2.x迁移

技术细节

需求

建筑

特性

版本历史记录

支持

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Qdrant向量搜索MCP服务器

Flomo笔记服务

Unity编辑器AI集成插件