Confluence (KMS) MCP Server
一个 Confluence MCP（Model Context Protocol）服务器：让 AI 在 Cursor 里通过自然语言创建、更新、删除、搜索 Confluence（公司内部也称 KMS）页面。
✨ 特性
- 页面管理：创建、更新、删除、获取页面（支持 title / pageId）
- 搜索能力：按关键词搜索、获取子页面、查看页面历史
- Space 管理：列出当前账号可访问的 Spaces
- 宏辅助：生成 Confluence Code Macro（storage format），安全插入代码块（规避
InvalidValueException）
⚠️ 注意事项（必读）
- 必须使用 Cursor 的 Agent 模式，才能调用
confluence_*这组 MCP 工具 - Cursor
mcp.json里的路径必须是绝对路径
📦 项目结构（以仓库现状为准）
confluence-node/
├── src/
│ └── mcp-server.ts # MCP Server 源码（TypeScript）
├── dist/
│ ├── mcp-server.js # 编译产物（Cursor 实际运行的入口）
│ └── mcp-server.js.map
├── dev/
│ ├── index.js # 开发/演示脚本（非 MCP）
│ └── test-connection.js # 连通性测试脚本
├── templates/ # 模板文件（如有）
├── env-example.txt # 环境变量示例
├── mcp-config-example.json # Cursor MCP 配置示例
├── package.json
├── tsconfig.json
└── README.md
🚀 快速开始
1) 安装依赖
npm install
2) 配置环境变量
复制 env-example.txt 为 .env，并填入你的配置：
CONF_BASE_URL=https://your-confluence-instance.atlassian.net
CONF_USERNAME=your-email@example.com
CONF_PASSWORD=your-api-token
CONF_SPACE=YOUR_SPACE_KEY
说明：本项目通过 Confluence REST API + Basic Auth（用户名 +
CONF_PASSWORD）访问。
- Atlassian Cloud：
CONF_PASSWORD通常是 API Token- 内部 KMS：以你们实际认证方式为准（可能是 Token 或密码）
3) 构建（生成 dist/）
npm run build
4) 配置 Cursor MCP
编辑 ~/.cursor/mcp.json（可参考 mcp-config-example.json），将 args 指向 本仓库的 dist/mcp-server.js 绝对路径：
{
"mcpServers": {
"confluence": {
"command": "node",
"args": ["/绝对路径/到/confluence-node/dist/mcp-server.js"],
"env": {
"CONF_BASE_URL": "你的 Confluence/KMS 地址（不要以 / 结尾）",
"CONF_USERNAME": "你的用户名/邮箱",
"CONF_PASSWORD": "你的 API Token/密码",
"CONF_SPACE": "默认 Space Key（可选）"
}
}
}
}
5) 重启 Cursor 并在 Agent 模式使用
- 完全退出并重启 Cursor
- 切换到 Agent 模式后再使用（否则 MCP 工具可能不可用）
6) 验证（在 Cursor 里直接问）
列出我可以访问的所有 KMS Spaces
🛠️ 可用工具
| 类别 | 工具 | 说明 |
|---|---|---|
| Space | confluence_list_spaces | 列出可访问的 Spaces |
| 页面操作 | confluence_create_page | 创建页面 |
confluence_update_page | 更新页面（支持 pageId 或 space+title） | |
confluence_upsert_page | 创建或更新（存在则更新，否则创建） | |
confluence_get_page | 获取页面详情（含 storage HTML） | |
confluence_delete_page | 删除页面 | |
| 搜索 | confluence_search_pages | 搜索页面 |
confluence_get_child_pages | 获取子页面 | |
confluence_get_page_history | 查看页面历史 | |
| 附件 | confluence_upload_attachment | 上传附件到指定页面（filePath 或 base64） |
| 宏 | confluence_build_code_macro | 生成 Code Macro（storage format HTML） |
🔧 开发与调试
运行 MCP Server（本地）
npm run mcp
测试连通性（推荐先跑）
npm test
使用 MCP Inspector 调试
npx @modelcontextprotocol/inspector node dist/mcp-server.js
Cursor MCP 日志位置
- macOS：
~/Library/Logs/Cursor/ - Windows：
%APPDATA%\\Cursor\\logs\\
🐛 故障排查
Cursor 里看不到 confluence_* 工具
- 确认在 Agent 模式下使用
- 检查
~/.cursor/mcp.json的args是否为 绝对路径，并指向dist/mcp-server.js - 运行
npm run mcp看是否能正常启动（无语法/依赖错误） - 完全重启 Cursor，并查看日志
认证失败（401/403）
- 检查
CONF_USERNAME / CONF_PASSWORD是否正确 - Atlassian Cloud 请使用 API Token；内部 KMS 以实际策略为准
- 确认账号对目标 Space 有权限，可用
confluence_list_spaces验证
Space Key 不确定
先执行：
列出我可以访问的所有 Confluence Spaces
📚 相关文档
- KMS 别名说明：
./KMS_ALIAS_README.md - Confluence REST API：
https://developer.atlassian.com/cloud/confluence/rest/v1/intro/ - MCP 协议：
https://modelcontextprotocol.io
📄 许可证
MIT