将AI连接到您的汇流知识库
通过将Claude、Cursor AI和其他AI助手直接连接到您的Confluence空间、页面和文档，改变您访问和与团队知识互动的方式。从您的知识库中获取即时答案，在所有空间中搜索，并简化您的文档工作流程。
](https://www.npmjs.com/package/@aashari/mcp-server-atlassian-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 ` （可选）-以JSON格式查询参数
- `--jq ` （可选）-JMESPath筛选器表达式
- `-o, --output-format ` （可选）-输出格式： `toon` （默认）或 `json`
**带有body的命令（post、put、patch）：**
- `-b, --body ` （必填）-请求正文为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": " Content here "}}'
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": " My comment "}}'
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": " Updated content "}, "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个令牌）时，服务器会自动截断响应以保持在令牌限制内。当这种情况发生时：
1. **你会看到一个截断通知** 在响应的末尾显示：
- 显示了多少原始响应
- 原始响应大小
- 获取完整数据的指南
1. **完整的原始响应已保存** 到中的临时文件 `/tmp/mcp/` （截断通知中提供的路径）
1. **避免截断的最佳实践：**
- **始终使用 `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禁止”
1. **检查您的API代币权限**:
- 首选 [大西洋API代币](https://id.atlassian.com/manage-profile/security/api-tokens)
- 确保您的令牌仍然有效且未过期
1. **验证您的网站名称格式**:
- 如果你的Confluence URL是 `https://mycompany.atlassian.net`
- 您的网站名称应该只是 `mycompany`
1. **测试您的凭据**:
npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces?limit=1"
### “找不到资源”或“404”
1. **检查API路径**:
- 路径区分大小写
- 对空格和页面使用数字ID（而不是键）
- 验证浏览器中是否存在该资源
1. **验证访问权限**:
- 确保您可以访问浏览器中的空间/页面
- 某些内容可能仅限于某些用户
### 搜索时“未找到结果”
1. **尝试不同的搜索词**:
- 使用CQL语法进行高级搜索
- 尝试更广泛的搜索条件
1. **检查CQL语法**:
- 首先在Confluence的高级搜索中验证您的CQL
### Claude桌面集成问题
1. **重新启动克劳德桌面** 更新配置文件后
1. **验证配置文件位置**:
- macOS： `~/.claude/claude_desktop_config.json`
- 窗户： `%APPDATA%\Claude\claude_desktop_config.json`
### 获取帮助
如果你仍然有问题：
1. 运行一个简单的测试命令来验证一切正常
1. 检查 对于类似的问题
1. 使用错误消息和设置详细信息创建新问题
## 常见问题
### 我需要什么权限？
您的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层架构：
1. **工具层** (`src/tools/`)-带Zod验证的MCP工具定义
1. **CLI层** (`src/cli/`)-基于命令行界面的直接测试
1. **控制器层** (`src/controllers/`)-业务逻辑、JMESPath过滤、输出格式化
1. **服务层** (`src/services/`)-汇流API通信
1. **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](CHANGELOG.md) 查看完整的版本历史记录。
## 支持
需要帮助？以下是如何获得帮助：
1. **检查上面的故障排除部分** -其中涵盖了最常见的问题
1. **访问我们的GitHub仓库** 有关文档和示例：
1. **报告问题** 在
1. **开始讨论** 用于功能请求或一般问题
______________________________________________________________________
*为希望将人工智能引入知识管理工作流程的团队精心打造。*