使用说明

汇流MCP服务器

用于Confluence云搜索和管理的模型上下文协议（MCP）服务器。使Claude Code能够连接到Confluence实例，通过内置的最佳实践linting搜索、阅读和管理文档。

特性

第一阶段：连接验证✅

confluence_ping -测试连接并验证身份验证
confluence_whoami -获取经过身份验证的用户信息
confluence_list_spaces -列出可访问的汇流空间

第二阶段：阅读与搜索✅

confluence_search -使用CQL（汇流查询语言）进行搜索
confluence_get_page_by_title -按确切标题查找页面
confluence_list_pages -列出空间中的页面
confluence_get_page -获取整页内容和元数据
confluence_get_page_metadata -获取不带正文的元数据
confluence_get_children -获取子页面

第3阶段：安全写入操作✅

confluence_create_page -创建新页面（使用模拟运行）
confluence_update_page -更新现有页面（使用模拟运行）
confluence_add_labels -为页面添加标签
confluence_remove_labels -从页面中删除标签
confluence_archive_page -存档页面（带模拟运行）

支持所有写入操作 dryRun: true 用于预览更改。

第四阶段：最佳实践✅

confluence_lint_page -检查违反最佳实践的页面
confluence_suggest_improvements -获取可操作的改进建议

检查：

标题约定（长度、格式、通用术语）
缺少元数据（所有者、上次审核日期）
内容结构（标题、段落、代码块）
标签（缺失或不标准）
稳定性（6个月以上未更新的页面）
嵌套深度过大（4+层）

设置

1.安装依赖项

cd ~/repos/confluence-mcp-server
npm install

2.配置环境

创建 .env 模板中的文件：

cp .env.example .env

编辑 .env 使用您的Confluence详细信息：

# Your Confluence Cloud instance
CONFLUENCE_BASE_URL=https://your-domain.atlassian.net

# Your Atlassian account email
CONFLUENCE_EMAIL=your-email@example.com

# API token (generate at https://id.atlassian.com/manage-profile/security/api-tokens)
CONFLUENCE_API_TOKEN=your-api-token-here

# Enable write operations (default: false)
CONFLUENCE_WRITE_ENABLED=false

# Optional: Restrict write operations to specific spaces
# CONFLUENCE_ALLOWED_SPACES=TEAM,DOCS,WIKI

# Optional: Enable audit logging (default: true)
CONFLUENCE_AUDIT_LOG=true

3.生成Confluence API令牌

首选https://id.atlassian.com/manage-profile/security/api-tokens
点击“创建API令牌”
给它起个名字（例如“克劳德代码MCP”）
复制令牌并将其粘贴到您的 .env 文件

4.添加到Claude代码配置

编辑 ~/.claude.json 并添加到全球 mcpServers 章节：

{
  "mcpServers": {
    "confluence": {
      "type": "stdio",
      "command": "/Users/joshuamullet/repos/confluence-mcp-server/start-mcp-server.sh",
      "args": [],
      "env": {}
    }
  }
}

重要提示：

使用绝对路径 start-mcp-server.sh
添加到全局 mcpServers，不在项目的内部 mcpServers
必须包括 "type": "stdio" 领域

5.重新启动克劳德代码

完全重启Claude Code以加载新的MCP服务器：

# Exit current session
/exit

# Start new session
claude-code

6.验证连接

在Claude Code中，检查服务器是否已加载：

/mcp

你应该看看 confluence 列出连接状态。

用法

连接测试

测试您的Confluence连接：

Can you ping the Confluence server and show me the current user?

克劳德会打电话的 confluence_ping 和 confluence_whoami 以验证连接。

搜索示例

搜索所有空间：

Search Confluence for pages about "API documentation"

搜索特定空间：

Search for pages in the TEAM space that contain "deployment"

高级CQL：

Search Confluence using this CQL: type=page AND space=DOCS AND lastModified >= "2025-01-01"

阅读示例

按标题获取页面：

Get the page titled "Getting Started" from the TEAM space

按ID获取页面：

Show me the content of Confluence page 123456

列表页面：

List all pages in the DOCS space

获取页面树：

Show me all child pages of page 123456

最佳实践

翻一页：

Lint Confluence page 123456 for best practice issues

获取改进建议：

Suggest improvements for Confluence page 123456

输出示例：

{
  "pageId": "123456",
  "pageTitle": "API Documentation",
  "totalFindings": 3,
  "findings": [
    {
      "severity": "warning",
      "category": "metadata",
      "message": "Missing owner or contact information",
      "recommendation": "Add an 'Owner' or 'Contact' section"
    },
    {
      "severity": "info",
      "category": "labels",
      "message": "Page has no labels",
      "recommendation": "Add labels to improve discoverability"
    }
  ]
}

写入操作（启用时）

重要提示： 写入操作需要 CONFLUENCE_WRITE_ENABLED=true 在你的 .env 文件。

创建页面：

Create a new page in the TEAM space titled "New Feature" with this content:
<h1>Overview</h1>
<p>This is a new feature.</p>

更新页面（先进行模拟运行）：

Update page 123456 with a new title "Updated Title" - show me what will change first

添加标签：

Add labels "documentation" and "api" to page 123456

安全

认证

使用Confluence Cloud API令牌（不是密码）
API令牌存储在 .env （被忽视，从未承诺）
通过HTTP基本身份验证进行身份验证（电子邮件+API令牌）

写保护

默认情况下禁用写入操作
需要明确 CONFLUENCE_WRITE_ENABLED=true
所有写入操作都支持干运行模式
可选空间允许列表限制修改

审计日志

所有工具调用都记录到stderr
日志包括：时间戳、工具名称、参数、成功/错误
敏感数据（API令牌）从未记录
查看日志： tail -f ~/.claude/logs/*.log

速率限制

自动检测429个响应
返回明确错误，信息后重试
使用回退实现基本重试逻辑

故障排除

服务器未出现在 `/mcp`

检查 ~/.claude.json 配置：
- 服务器是否位于全局 mcpServers 部分？
- 是通往 start-mcp-server.sh 绝对正确？
- 是 "type": "stdio" 现在？
检查服务器是否手动启动：
```
cd ~/repos/confluence-mcp-server
node mcp-server.js
```
应输出： Confluence MCP Server running on stdio
检查克劳德代码日志：
```
tail -f ~/.claude/logs/*.log
```

身份验证错误

验证 CONFLUENCE_BASE_URL 是正确的（应该是 https://your-domain.atlassian.net)
验证 CONFLUENCE_EMAIL 匹配您的Atlassian帐户
如果需要，重新生成API令牌

手动测试凭据：

curl -u "your-email:your-token" "https://your-domain.atlassian.net/wiki/rest/api/space"

写入操作已禁用

检查 CONFLUENCE_WRITE_ENABLED=true 在 .env
更改后重新启动Claude代码 .env
验证加载的设置：服务器日志显示“写入操作：已启用”

缺少环境变量

错误： Missing required environment variables

解决方案：

确保 .env 文件存在于服务器目录中
验证是否设置了所有必需的变量
检查dotenv是否正在加载（请参阅服务器启动日志）

api参考

使用CQL搜索

CQL（汇流查询语言）示例：

type=page AND space=TEAM
type=page AND title~"API"
type=page AND space=DOCS AND lastModified >= "2025-01-01"
type=page AND label="documentation"
creator=currentUser()

看汇流CQL文档更多。

分页

大多数列表操作都支持分页：

{
  "limit": 25,    // Results per page (max 100)
  "start": 0      // Offset (0 = first page, 25 = second page, etc.)
}

干运行模式

所有写入操作都支持模拟运行：

{
  "pageId": "123456",
  "title": "New Title",
  "dryRun": true  // Preview changes without applying
}

返回在不进行实际修改的情况下会更改的内容。

发展

项目结构

confluence-mcp-server/
├── mcp-server.js              # Main MCP server (loads dotenv first)
├── start-mcp-server.sh        # Shell wrapper for Claude Code
├── tools/
│   ├── confluence-client.js   # Confluence REST API client
│   └── best-practices.js      # Linting and suggestions
├── package.json
├── .env                       # Your credentials (gitignored)
├── .env.example               # Template
├── .gitignore
└── README.md

手动测试

测试单个API调用：

cd ~/repos/confluence-mcp-server
node -e "
import('./tools/confluence-client.js').then(async ({ ConfluenceClient }) => {
  const client = new ConfluenceClient(
    process.env.CONFLUENCE_BASE_URL,
    process.env.CONFLUENCE_EMAIL,
    process.env.CONFLUENCE_API_TOKEN
  );
  const result = await client.ping();
  console.log(result);
});
"

资源

许可证

ISC