Skip to main content
Glama
enjoyzl

MCP Confluence Server

by enjoyzl
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

MCP Confluence 服务

这是一个基于 MCP (Model Context Protocol) 的 Confluence API 服务实现。该服务提供了与 Confluence 进行交互的能力，支持获取空间信息、页面内容、搜索等功能。

目录

功能特性

🔐 认证方式

  • Access Token 认证（推荐）

  • 用户名密码认证

  • 支持多环境配置

🔧 MCP 工具架构（已优化）

  • 工具合并优化: 从12个工具精简为8个（减少33%）

  • 统一API设计: 通过action参数区分操作类型

  • 智能参数验证: 根据操作自动验证必需参数

  • 完整参数注释: MCP Inspector中可查看详细说明

📄 页面管理功能

  • managePages: 统一页面管理工具 ⭐️

    • 创建页面（支持父页面和内容格式）

    • 更新页面（增量更新支持）

    • 删除页面 ⭐️ 新增功能

    • 获取页面基本信息

    • 获取页面详细内容

    • Markdown支持 🆕 自动转换为HTML

  • getPageByPrettyUrl: 通过标题精确获取页面

  • getSpace: 获取空间信息

💬 评论管理功能

  • manageComments: 统一评论管理工具 ⭐️

    • 普通评论: 创建、更新、删除、回复

    • 行内评论: 创建、更新、删除、回复

    • 支持评论版本控制和监视

    • Markdown支持 🆕 智能检测与转换

  • getPageComments: 获取页面所有评论（支持分页）

  • getComment: 获取单个评论详情

🔍 搜索功能

  • searchContent: 全文搜索内容（支持CQL语法）

  • searchComments: 搜索评论内容（支持空间限定）

  • 错误回退机制: CQL语法错误时自动尝试基本搜索

⚡ 性能优化

  • HTTP 连接复用: Keep-Alive支持

  • 响应压缩: 自动压缩传输

  • 请求超时控制: 可配置超时时间

  • 错误重试机制: 自动重试失败请求

📊 日志和监控

  • 结构化日志输出: JSON格式日志

  • 请求耗时统计: 性能监控

  • 详细错误信息: 便于调试

  • 操作记录追踪: 完整的操作日志

快速开始

环境要求

  • Node.js >= 14.0.0

  • TypeScript >= 4.0.0

安装

# 安装依赖 npm install

构建

# 清理并构建项目 npm run build:clean

启动服务

# 启动服务 npm start

配置说明

认证配置

服务支持两种认证方式，你可以选择其中一种：

1. Access Token 认证（推荐）

在 .env 文件中配置：

CONFLUENCE_URL=https://your-confluence-url CONFLUENCE_ACCESS_TOKEN=your-access-token

2. 用户名密码认证

在 .env 文件中配置：

CONFLUENCE_URL=https://your-confluence-url CONFLUENCE_USERNAME=your-username CONFLUENCE_PASSWORD=your-password

其他配置项

# 服务器配置 PORT=3000 NODE_ENV=development TIMEOUT=10000 REJECT_UNAUTHORIZED=true

Cursor IDE 配置

Windows 配置

  1. 使用 Smithery（推荐） 在 %USERPROFILE%\.cursor\mcp.json 中添加：

{ "mcpServers": { "mcp-server-confluence-ts": { "command": "cmd", "args": [ "/c", "npx", "-y", "@smithery/cli@latest", "run", "@enjoyzl/mcp-server-confluence-ts", "--config", "{\"confluenceUrl\":\"your-confluence-url\",\"confluenceUsername\":\"your-username\",\"confluencePassword\":\"your-password\"}" ] } } }

  1. 本地服务方式 在 %USERPROFILE%\.cursor\mcp.json 中添加：

{ "mcpServers": { "mcp-server-confluence-ts": { "command": "cmd", "args": [ "/k", "cd", "/d", "D:\\workspace\\code\\mcp\\mcp-server-confluence-ts", "&", "node", "dist/index.js" ] } } }

Windows 配置说明：

  • /k: 执行命令后保持命令窗口，便于查看日志

  • /d: 切换到指定驱动器

  • 使用 & 连接多个命令

  • 路径使用双反斜杠 \\ 转义

  • 环境变量可以在项目的 .env 文件中配置

Mac/Linux 配置

  1. 使用 Smithery（推荐） 在 ~/.cursor/mcp.json 中添加：

{ "mcpServers": { "mcp-server-confluence-ts": { "command": "bash", "args": [ "-c", "npx -y @smithery/cli@latest run @enjoyzl/mcp-server-confluence-ts --config '{\"confluenceUrl\":\"your-confluence-url\",\"confluenceUsername\":\"your-username\",\"confluencePassword\":\"your-password\"}'" ] } } }

  1. 本地服务方式 在 ~/.cursor/mcp.json 中添加：

{ "mcpServers": { "mcp-server-confluence-ts": { "command": "node", "args": ["/Users/your-username/workspace/code/mcp/mcp-server-confluence-ts/dist/index.js"], "env": { "CONFLUENCE_URL": "your-confluence-url", "CONFLUENCE_USERNAME": "youraccount", "CONFLUENCE_PASSWORD": "yourpwd", } } } }

Mac/Linux 配置说明：

  • -c: 执行命令字符串

  • 使用 && 连接多个命令

  • 路径使用正斜杠 /

  • 环境变量可以在项目的 .env 文件中配置

  • Mac 用户主目录通常在 /Users/your-username/

  • Linux 用户主目录通常在 /home/your-username/

开发模式

# 监听文件变化并自动编译 npm run dev # 监听文件变化并自动重启服务 npm run dev:start

构建命令

# 仅构建项目 npm run build # 清理构建目录 npm run clean # 清理并重新构建 npm run build:clean

调试工具

# 基本调试模式 npm run inspector # 开发调试模式（带详细日志） npm run inspector:dev

MCP 工具使用指南

🚀 工具架构优化

本服务已完成工具架构优化，按功能和使用频率重新组织：

📁 1. 基础信息工具（最常用） 📁 2. 页面管理工具（核心功能） 📁 3. 评论管理工具（扩展功能） 📁 4. 搜索工具（专用搜索）

🔧 MCP 工具列表

1. 基础信息工具 - 最常用的查询功能

getSpace - 获取空间信息

{ "name": "getSpace", "arguments": { "spaceKey": "DEV" } }

getPageByPrettyUrl - 根据标题精确获取页面

{ "name": "getPageByPrettyUrl", "arguments": { "spaceKey": "DEV", "title": "API 开发指南" } }

2. 页面管理工具 - 核心功能

managePages - 统一页面管理 ⭐️ 合并优化

创建页面：

{ "name": "managePages", "arguments": { "action": "create", "spaceKey": "DEV", "title": "新页面标题", "content": "<p>页面内容</p>", "parentId": "123456789", "representation": "storage" } }

更新页面：

{ "name": "managePages", "arguments": { "action": "update", "pageId": "123456789", "title": "更新的标题", "content": "<p>更新的内容</p>", "version": 2, "representation": "storage" } }

删除页面： ⭐️ 新增功能

{ "name": "managePages", "arguments": { "action": "delete", "pageId": "123456789" } }

获取页面基本信息：

{ "name": "managePages", "arguments": { "action": "get", "pageId": "123456789" } }

获取页面详细内容：

{ "name": "managePages", "arguments": { "action": "getContent", "pageId": "123456789", "expand": "body.storage,version,space" } }

3. 评论管理工具 - 扩展功能

manageComments - 统一评论管理 ⭐️ 合并优化

创建普通评论（HTML格式）：

{ "name": "manageComments", "arguments": { "action": "create", "commentType": "regular", "pageId": "123456789", "content": "这是一条普通评论", "representation": "storage" } }

创建普通评论（Markdown格式）： 🆕

{ "name": "manageComments", "arguments": { "action": "create", "commentType": "regular", "pageId": "123456789", "content": "## 代码审查意见\n\n这段代码需要优化：\n\n- **性能问题**: 数据库查询未优化\n- **安全问题**: 缺少输入验证\n\n建议修改：\n\n``javascript\n// 使用索引查询\nconst user = await User.findById(id).lean();\n```", "representation": "markdown" } }

创建行内评论：

{ "name": "manageComments", "arguments": { "action": "create", "commentType": "inline", "pageId": "123456789", "content": "这里需要注意性能问题", "originalSelection": "QueryHoldingsService.setHoldingData()", "matchIndex": 0, "numMatches": 1 } }

更新评论：

{ "name": "manageComments", "arguments": { "action": "update", "commentType": "regular", "commentId": "98765432", "content": "更新后的评论内容", "version": 2 } }

删除评论：

{ "name": "manageComments", "arguments": { "action": "delete", "commentType": "regular", "commentId": "98765432" } }

回复普通评论：

{ "name": "manageComments", "arguments": { "action": "reply", "commentType": "regular", "pageId": "123456789", "parentCommentId": "98765432", "content": "这是一条回复", "watch": false } }

回复行内评论：

{ "name": "manageComments", "arguments": { "action": "reply", "commentType": "inline", "commentId": "98765432", "pageId": "123456789", "content": "这是对行内评论的回复" } }

getPageComments - 获取页面所有评论

{ "name": "getPageComments", "arguments": { "pageId": "123456789", "start": 0, "limit": 25 } }

getComment - 获取单个评论详情

{ "name": "getComment", "arguments": { "commentId": "98765432" } }

4. 搜索工具 - 专用搜索功能

searchContent - 搜索页面内容（支持CQL）

{ "name": "searchContent", "arguments": { "query": "API 开发" } }

searchComments - 搜索评论内容

{ "name": "searchComments", "arguments": { "query": "性能优化", "spaceKey": "DEV", "start": 0, "limit": 25 } }

📝 参数说明

action 参数选项：

  • 页面管理: create, update, delete, get, getContent

  • 评论管理: create, update, delete, reply

commentType 参数选项：

  • regular (默认): 普通评论

  • inline: 行内评论

representation 参数选项：

  • storage (推荐): HTML存储格式

  • wiki: Wiki标记语法

  • editor2: 编辑器格式

  • view: 查看格式

  • markdown 🆕: Markdown格式（自动转换为HTML）

🎯 优化亮点

✅ 工具数量优化: 从12个工具合并为8个（减少33%）
✅ 统一API设计: 通过action参数区分操作类型
✅ 智能参数验证: 根据操作类型自动验证必需参数
✅ 完整参数注释: MCP Inspector中可查看详细参数说明
✅ 新增删除功能: 支持删除页面操作
✅ 双评论类型: 统一管理普通评论和行内评论

🚀 新功能：Markdown 导出

导出功能概览

现在支持将 Confluence 页面导出为 Markdown 文件到当前工作空间！

🎯 支持的导出方式

  1. 单页面导出 (exportPage)

    • 导出指定页面为 Markdown 文件

    • 支持按章节拆分大文档

    • 可选的 YAML frontmatter 元数据

  2. 层次结构导出 (exportPageHierarchy)

    • 递归导出页面及其所有子页面

    • 保持原有的目录层次结构

    • 可控制递归深度

  3. 批量导出 (batchExportPages)

    • 同时导出多个指定页面

    • 智能并发控制和错误处理

    • 性能优化和进度跟踪

🌟 核心特性

  • ✅ 智能内容转换: 高质量的 HTML 到 Markdown 转换

  • ✅ 章节拆分: 根据标题级别自动拆分大文档

  • ✅ 元数据保留: 完整的页面信息作为 YAML frontmatter

  • ✅ 文件管理: 智能文件命名和冲突处理

  • ✅ 性能优化: 并发控制、重试机制、内存优化

  • ✅ 进度跟踪: 实时导出状态和错误报告

📖 快速开始

# 导出单个页面 { "pageId": "123456789", "outputDir": "my-docs", "includeMetadata": true } # 按章节拆分导出 { "pageId": "123456789", "splitByChapters": true, "splitLevel": "2" } # 导出页面层次结构 { "pageId": "123456789", "maxDepth": 3, "includeChildren": true } # 批量导出多个页面 { "pageIds": ["123", "456", "789"], "concurrency": 3 }

📁 输出示例

confluence-export/ ├── API_Documentation.md # 单页面导出 ├── User_Guide/ # 层次结构导出 │ ├── User_Guide.md │ ├── Getting_Started/ │ │ └── Installation.md │ └── Advanced_Topics/ │ └── Configuration.md └── Large_Document/ # 章节拆分导出 ├── README.md # 章节索引 ├── 01_introduction.md ├── 02_setup.md └── 03_usage.md

详细使用指南请参考：导出功能指南

安全建议

  1. 优先使用 Access Token 认证方式，这样更安全

  2. 定期轮换 Access Token

  3. 不要在代码中硬编码认证信息

  4. 确保 .env 文件已添加到 .gitignore 中

  5. 在生产环境中使用环境变量或安全的配置管理系统

  6. 如果同时配置了两种认证方式，系统会优先使用 Access Token

注意事项

  1. Access Token 和用户名密码认证方式只能选择其中一种

  2. 如果同时配置了两种认证方式，系统会优先使用 Access Token

  3. 确保配置的 URL 是正确的 Confluence API 地址

  4. 在生产环境中建议使用 HTTPS

性能优化

  1. 连接优化

    • 启用 HTTP Keep-Alive

    • 限制最大并发连接数

    • 控制空闲连接数

  2. 请求优化

    • 响应压缩

    • 超时控制

    • 重定向限制

  3. 错误处理

    • 自动重试机制

    • 详细的错误信息

    • 请求耗时统计

调试指南

日志输出

服务使用结构化日志输出，包含以下信息：

{ "jsonrpc": "2.0", "method": "log", "params": { "level": "info", "message": "请求信息", "timestamp": "2024-04-16T12:00:44.000Z" } }

错误处理

错误响应格式：

interface ErrorResponse { message: string; statusCode?: number; error?: any; config?: { url?: string; method?: string; params?: any; }; }

工具概览

🎯 架构优化后的工具分组

经过架构优化，工具按使用频率和逻辑分组重新组织：

📁 1. 基础信息工具（最常用）

  • getSpace - 获取空间信息

  • getPageByPrettyUrl - 根据标题精确获取页面

📁 2. 页面管理工具（核心功能）

  • managePages ⭐️ - 统一页面管理（create/update/delete/get/getContent）

📁 3. 评论管理工具（扩展功能）

  • manageComments ⭐️ - 统一评论管理（create/update/delete/reply，支持普通+行内评论）

  • getPageComments - 获取页面所有评论

  • getComment - 获取单个评论详情

📁 4. 搜索工具（专用搜索）

  • searchContent - 搜索页面内容（支持CQL语法）

  • searchComments - 搜索评论内容

📊 优化成果

  • 工具数量: 从12个优化为8个（减少33%）

  • API统一: 合并同类功能，通过action参数区分操作

  • 功能增强: 新增页面删除、完善参数注释

  • 体验提升: 按使用频率排序，提高查找效率

文档

贡献

欢迎提交 Issue 和 Pull Request。

许可证

MIT License

配置

环境变量配置

在项目根目录创建 .env 文件，配置以下参数：

# Confluence 连接配置 CONFLUENCE_URL=https://your-confluence.com CONFLUENCE_USERNAME=your-username CONFLUENCE_PASSWORD=your-password # 或者使用访问令牌 CONFLUENCE_ACCESS_TOKEN=your-access-token # 服务器配置 PORT=3000 NODE_ENV=development SERVER_TIMEOUT=10000 # 评论 API 策略配置 COMMENT_API_STRATEGY=standard COMMENT_ENABLE_FALLBACK=true COMMENT_TIMEOUT=15000

评论策略配置说明

评论功能支持三种API实现策略，可通过环境变量 COMMENT_API_STRATEGY 配置：

1. standard (默认，推荐)

  • 使用标准 REST API

  • 兼容性好，适合 Confluence 7.4+

  • 稳定性高，适合生产环境

2. tinymce

  • 使用 TinyMCE 端点

  • 功能更丰富，模拟浏览器行为

  • 支持更复杂的评论功能

3. auto

  • 自动选择策略

  • 优先使用 TinyMCE，失败时回退到标准 API

  • 平衡功能性和兼容性

其他评论配置

  • COMMENT_ENABLE_FALLBACK: 是否启用回退机制 (默认: true)

    • true: 当首选API失败时，自动尝试备用API

    • false: 只使用指定的API，失败时直接抛出错误

  • COMMENT_TIMEOUT: 评论请求超时时间，单位毫秒 (默认: 15000)

    • 建议标准API使用 10-15 秒

    • TinyMCE API 由于需要获取token等步骤，建议 15-20 秒

Confluence 7.4 特别说明

  • 标准API在7.4版本中稳定性更好

  • TinyMCE API提供更丰富的功能，但可能有兼容性问题

  • 建议在生产环境使用 standard 策略，开发环境可根据需要选择

部署到私有 npm 仓库

登录仓库参考: [PRIVATE_DOCUMENTATION_URL]

# 登录并部署 npm login --registry=[PRIVATE_REGISTRY] npm publish @[ORGANIZATION]/mcp-server-confluence-ts

Claude CLI 安装（推荐）

``shell claude mcp add --transport stdio mcp-server-confluence-ts -- npx --registry=[PRIVATE_REGISTRY] -y @[ORGANIZATION]/mcp-server-confluence-ts

#### Cursor 安装 **Cursor MCP 配置文件** (通常位于 `~/.cursor/settings.json` 或项目 `.cursor/mcp.json`): ```json { "mcpServers": { "mcp-server-confluence-ts": { "command": "npx", "args": ["--registry=[PRIVATE_REGISTRY]","-y", "@[ORGANIZATION]/mcp-server-confluence-ts"], "env": { "CONFLUENCE_URL": "your-confluence-url", "CONFLUENCE_USERNAME": "youraccount", "CONFLUENCE_PASSWORD": "yourpwd", } } } }

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/enjoyzl/mcp-server-confluence-ts'

If you have feedback or need assistance with the MCP directory API, please join our Discord server