知识搜索
一个模型上下文协议服务器,使像 Claude 这样的人工智能助手能够访问和搜索 Atlassian Confluence 内容,从而实现与您组织的知识库的集成。
MCP 服务配置
复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用
{
"mcpServers": {
"confluence": {
"args": [
"-y",
"@aashari/mcp-server-atlassian-confluence"
],
"command": "npx"
}
}
}
该服务需要配置环境变量:ATLASSIAN_API_TOKEN、ATLASSIAN_SITE_NAME、ATLASSIAN_USER_EMAIL、DEBUG
可用工具 (5 个)
该服务在 MCP 协议中暴露的工具,AI 可按需调用
list-spaces 4 个参数
List Confluence spaces with optional filtering capabilities. PURPOSE: Discovers available spaces in your Confluence instance with their keys, names, types, and URLs. WHEN TO USE: - When you need to discover what spaces exist in your Confluence instance - When you want to find spaces by type (global, personal, archived) - When you need to browse available spaces before accessing specific pages - When you need space keys for use with other Confluence tools WHEN NOT TO USE: - When you already know the specific space key/ID (use get-space instead) - When you need detailed information about a specific space (use get-space instead) - When you need to find content across multiple spaces (use search instead) - When you need to list pages within a specific space (use list-pages instead) RETURNS: Formatted list of spaces with IDs, keys, names, types, and URLs, plus pagination info. EXAMPLES: - List all spaces: {} - Filter by type: {type: "global"} - With pagination: {limit: 10, cursor: "next-page-token"} ERRORS: - Authentication failures: Check your Confluence credentials - No spaces found: Verify your permissions in Confluence - Rate limiting: Use pagination and reduce query frequency
该工具无需必填参数,直接调用即可
get-space 1 个参数 需填 1 项
Get detailed information about a specific Confluence space by ID or key. PURPOSE: Retrieves comprehensive space metadata including description, homepage, permissions, and more. WHEN TO USE: - When you need detailed information about a specific space - When you need to find the homepage or key pages within a space - When you need to verify space permissions or settings - After using list-spaces to identify the relevant space WHEN NOT TO USE: - When you don't know which space to look for (use list-spaces first) - When you need to browse multiple spaces (use list-spaces instead) - When you need to find specific content (use search or list-pages instead) RETURNS: Detailed space information including key, name, description, type, homepage, and metadata. EXAMPLES: - By key: {idOrKey: "DEV"} - By ID: {idOrKey: "123456"} ERRORS: - Space not found: Verify the space key or ID is correct - Permission errors: Ensure you have access to the requested space - Rate limiting: Cache space information when possible
必填参数:id
list-pages 4 个参数
List Confluence pages with optional filtering by space and status. PURPOSE: Finds pages within Confluence spaces with their IDs, titles, and locations to help you discover available content. WHEN TO USE: - When you need to find pages within a specific space - When you want to list the most recently updated content - When you need to browse available pages before accessing specific content - When you need page IDs for use with other Confluence tools - When looking for pages with specific statuses (current, draft, trashed) WHEN NOT TO USE: - When you already know the specific page ID (use get-page instead) - When you need the actual content of a page (use get-page instead) - When you need to search across multiple spaces (use search instead) - When you need to find spaces rather than pages (use list-spaces instead) RETURNS: Formatted list of pages with IDs, titles, space information, and URLs, plus pagination info. EXAMPLES: - Pages in a space: {spaceId: "DEV"} - With status filter: {spaceId: "DEV", status: "current"} - With pagination: {spaceId: "DEV", limit: 10, cursor: "next-page-token"} ERRORS: - Space not found: Verify the space ID is correct - Authentication failures: Check your Confluence credentials - No pages found: The space might be empty or you lack permissions - Rate limiting: Use pagination and reduce query frequency
该工具无需必填参数,直接调用即可
get-page 1 个参数 需填 1 项
Get detailed information and content of a specific Confluence page by ID. PURPOSE: Retrieves the full content of a page in Markdown format along with comprehensive metadata. WHEN TO USE: - When you need to read the actual content of a page - When you need detailed page metadata (author, dates, versions) - When you need to extract specific information from a page - After using list-pages or search to identify relevant page IDs WHEN NOT TO USE: - When you don't know which page to look for (use list-pages or search first) - When you only need basic page information without content (use list-pages instead) - When you need to find content across multiple pages (use search instead) RETURNS: Complete page content in Markdown format with metadata including title, author, version, space, and creation/modification dates. EXAMPLES: - By ID: {id: "123456"} ERRORS: - Page not found: Verify the page ID is correct - Permission errors: Ensure you have access to the requested page - Rate limiting: Cache page content when possible for frequently accessed pages
必填参数:id
search 3 个参数 需填 1 项
Search for content across Confluence using Confluence Query Language (CQL). PURPOSE: Finds content matching specific criteria with excerpts showing matches, helping you discover relevant information across spaces. WHEN TO USE: - When you need to find specific content across multiple spaces - When you want to search by various criteria (text, title, labels, content type) - When you need to gather information scattered across different pages - When you're unfamiliar with the structure of Confluence and need discovery - When looking for content with specific labels or within specific date ranges WHEN NOT TO USE: - When you already know the exact space and page (use get-page instead) - When you want to list all spaces or pages systematically (use list-spaces/list-pages) - When performing many rapid, consecutive searches (consider rate limits) - When you need to retrieve complete page content (use get-page after search) RETURNS: Search results with titles, excerpts showing matches, content types, spaces, and URLs, plus pagination info. EXAMPLES: - Simple text search: {cql: "text~documentation"} - Space-specific search: {cql: "space=DEV AND text~API"} - Title search: {cql: "title~Project Plan"} - Content type filter: {cql: "type=page AND label=important"} - With pagination: {cql: "text~API", limit: 10, cursor: "next-page-token"} ERRORS: - Invalid CQL syntax: Check CQL syntax (example: "type=page AND space=DEV") - No results: Try broader search terms or check different spaces - Authentication failures: Check your Confluence credentials - Rate limiting: Use more specific queries and pagination
必填参数:cql
服务介绍
Atlassian Confluence MCP 服务器
该项目提供了一个模型上下文协议(MCP)服务器,作为AI助手(如Anthropic的Claude、Cursor AI或其他MCP兼容客户端)和您的Atlassian Confluence实例之间的桥梁。它允许AI实时安全地访问和与您的Confluence空间和页面进行交互。
什么是MCP以及为什么要使用此服务器?
模型上下文协议(MCP)是一个开放标准,使AI模型能够安全地连接到外部工具和数据源。此服务器专门为Confluence实现了MCP。
优势:
- 实时访问: 您的AI助手可以直接访问最新的Confluence内容。
- 消除复制/粘贴: 无需手动在Confluence和您的AI助手之间传输信息。
- 增强的AI功能: 使AI能够搜索、总结、分析并引用您的Confluence文档中的内容。
- 安全性: 您可以通过API令牌控制访问权限。AI通过服务器进行交互,敏感操作被限制在服务器内。
可用工具
此MCP服务器为您的AI助手提供了以下工具:
- **Page Search:** Allows the AI to search for specific pages within your Confluence instance.
- **Page Content Retrieval:** Enables the AI to fetch the content of a specific page.
- **Page Creation and Editing:** The AI can create new pages or edit existing ones.
- **Space Management:** The AI can list, create, and manage spaces in your Confluence instance.
请根据实际需求继续添加更多工具及其描述。
-
列出空间 (
list-spaces)- 目的: 发现可用的 Confluence 空间并找到它们的“键”(唯一标识符)。
- 使用时机: 当你需要知道存在哪些空间、查找某个空间的键,或者按类型/状态过滤空间时。
- 对话示例: “显示所有的 Confluence 空间。”
- 参数示例:
{}(基本列表不需要参数)或{ type: "global", status: "current" }(用于过滤)。
-
获取空间 (
get-space)- 目的: 使用其键检索关于特定空间的详细信息。包括主页内容片段。
- 使用时机: 当你知道空间键(例如,“DEV”)并且需要其完整详细信息、标签或主页概览时。
- 对话示例: “告诉我 Confluence 中 'DEV' 空间的详情。”
- 参数示例:
{ spaceKey: "DEV" }
-
列出页面 (
list-pages)- 目的: 列出特定空间内的页面(使用数字空间 ID),或者在整个实例中列出页面,并提供过滤选项。
- 使用时机: 当你需要在已知空间中查找页面(需要数字 ID)、按状态过滤,或者对标题/标签进行简单的文本搜索时。
- 对话示例: “显示空间 ID 123456 中当前的页面。”(如果你只知道键,请先使用
list-spaces)。 - 参数示例:
{ spaceId: ["123456"] }或{ status: ["archived"], query: "Meeting Notes" }。
-
获取页面 (
get-page)- 目的: 使用页面的数字 ID 检索特定页面的完整内容(以 Markdown 格式)和元数据。
- 使用时机: 当你知道页面的数字 ID(通过
list-pages或search找到)并且需要阅读、分析或总结其内容时。 - 对话示例: “获取 Confluence 页面 ID 12345678 的内容。”
- 参数示例:
{ pageId: "12345678" }
-
搜索 (
search)- 目的: 使用 CQL(Confluence 查询语言)对 Confluence 内容(页面、博客、附件)执行强大的搜索。
- 使用时机: 当你需要涉及多个条件的复杂搜索、全文搜索或按标签、日期、贡献者等进行过滤时。
- 对话示例: “搜索上周创建的带有 'meeting-notes' 标签的 Confluence 页面。”
- 参数示例:
{ cql: "label = meeting-notes AND created > -7d" }
接口理念:简单输入,丰富输出
该服务器遵循“最小接口,最大细节”的方法:
- 简单工具: 只请求必要的标识符或过滤器(如
pageId、spaceKey、cql)。 - 丰富细节: 当你请求特定项目(如
get-page)时,服务器默认提供所有相关信息(内容、标签、链接等),而无需额外的标志。
前提条件
- Node.js 和 npm: 确保已安装 Node.js(包含 npm)。从 nodejs.org 下载。
- Atlassian 账户: 一个可以访问你想连接的 Confluence 实例的有效 Atlassian 账户。
快速入门指南
按照以下步骤将您的 AI 助手连接到 Confluence:
第 1 步:获取您的 Atlassian API 令牌
**重要提示:**请像对待密码一样对待您的 API 令牌。不要与他人共享,也不要将其提交到版本控制系统中。
- 前往您的 Atlassian API 令牌管理页面:
https://id.atlassian.com/manage-profile/security/api-tokens - 点击 创建 API 令牌。
- 给它一个描述性的标签(例如,
mcp-confluence-access)。 - 点击 创建。
- 立即复制生成的 API 令牌。 您之后无法再次查看该令牌。请安全地保存它。
第 2 步:配置服务器凭据
请选择以下方法中的一种:
方法 A:全局 MCP 配置文件(推荐)
这种方式可以让凭据分开且有组织。
-
创建目录(如果需要的话):
~/.mcp/ -
创建/编辑文件:
~/.mcp/configs.json -
添加配置: 复制以下 JSON 结构并替换占位符:
{ "@aashari/mcp-server-atlassian-confluence": { "environments": { "ATLASSIAN_SITE_NAME": "<YOUR_SITE_NAME>", "ATLASSIAN_USER_EMAIL": "<YOUR_ATLASSIAN_EMAIL>", "ATLASSIAN_API_TOKEN": "<YOUR_COPIED_API_TOKEN>" } } // 如果需要,此处可添加其他服务器 }<YOUR_SITE_NAME>: 您的 Confluence 站点名称(例如,对于mycompany.atlassian.net使用mycompany)。<YOUR_ATLASSIAN_EMAIL>: 您的 Atlassian 账户邮箱。<YOUR_COPIED_API_TOKEN>: 从第 1 步复制的 API 令牌。
方法 B:环境变量(替代方案)
在运行服务器时设置环境变量。
ATLASSIAN_SITE_NAME="<YOUR_SITE_NAME>" \
ATLASSIAN_USER_EMAIL="<YOUR_EMAIL>" \
ATLASSIAN_API_TOKEN="<YOUR_API_TOKEN>" \
npx -y @aashari/mcp-server-atlassian-confluence
第 3 步:连接您的 AI 助手
配置您的 MCP 客户端(如 Claude Desktop, Cursor 等)以运行此服务器。
Claude Desktop
-
打开设置(齿轮图标)> 编辑配置。
-
添加或合并到
mcpServers中:{ "mcpServers": { "aashari/mcp-server-atlassian-confluence": { "command": "npx", "args": ["-y", "@aashari/mcp-server-atlassian-confluence"] } // ... 其他服务器 } } -
保存并重启 Claude Desktop。
-
验证: 点击“工具”(锤子图标);Confluence 工具应被列出。
Cursor AI
- 命令面板 (
Cmd+Shift+P/Ctrl+Shift+P) > Cursor 设置 > MCP。 - 点击 + 添加新的 MCP 服务器。
- 输入:
- 名称:
aashari/mcp-server-atlassian-confluence - 类型:
command - 命令:
npx -y @aashari/mcp-server-atlassian-confluence
- 名称:
- 点击 添加。
- 验证: 等待服务器名称旁边的指示器变为绿色。
第 4 步:使用工具
现在您可以向您的 AI 助手询问有关您的 Confluence 实例的问题了:
- "列出 Confluence 空间。"
- "使用 CQL 搜索 Confluence:
label = meeting-notes AND created > -7d" - "获取 Confluence 页面 ID 12345678 的内容。"
- "总结 DEV 空间中的 'API Guidelines' 页面。"(你可能需要先使用
search或list-pages来找到页面 ID)。
作为命令行工具 (CLI) 使用
你也可以直接从终端使用此包。请确保首先设置好凭证(上面的方法 A 或 B)。
使用 npx 快速使用
npx -y @aashari/mcp-server-atlassian-confluence list-spaces
npx -y @aashari/mcp-server-atlassian-confluence get-page --page 123456
npx -y @aashari/mcp-server-atlassian-confluence search --cql "type=page AND text~API" --limit 10
全局安装(可选)
npm install -g @aashari/mcp-server-atlassian-confluence- 使用
mcp-atlassian-confluence命令:
mcp-atlassian-confluence list-spaces --limit 5
mcp-atlassian-confluence get-space --space DEV
mcp-atlassian-confluence list-pages --space-id 12345 --status archived
mcp-atlassian-confluence --help # See all commands
故障排除
- 认证错误 (401/403):
- 检查
~/.mcp/configs.json或环境变量中的ATLASSIAN_SITE_NAME、ATLASSIAN_USER_EMAIL和ATLASSIAN_API_TOKEN。 - 确保证书是正确的、有效的,并且未被撤销。
- 确认您的用户帐户有权访问 Confluence 实例和相关空间/页面。
- 检查
- 服务器无法连接(在 AI 客户端中):
- 确保客户端配置中的命令 (
npx ...) 是正确的。 - 检查 Node.js/npm 安装和 PATH。
- 在终端中直接运行
npx命令以查看错误信息。
- 确保客户端配置中的命令 (
- 资源未找到 (404):
- 验证
pageId(必须是数字)或spaceKey是否正确。 - 检查您对特定页面或空间的权限。
- 验证
- CQL 查询错误 (400):
- 仔细检查 CQL 语法。参考 Confluence CQL 文档。
- 确认字段名称和值有效。
- 启用调试日志: 设置
DEBUG=true环境变量(例如,在configs.json中添加"DEBUG": "true"或运行DEBUG=true npx ...)。
对开发者:贡献
欢迎贡献!如果你想参与贡献:
- 架构: 该服务器采用了分层方法(CLI/工具 -> 控制器 -> 服务)。详情请参见
.cursorrules或代码注释。 - 设置: 克隆仓库,
npm install。使用npm run dev:server或npm run dev:cli -- <command>。 - 代码风格: 使用
npm run lint和npm run format。 - 测试: 通过
npm test添加测试。 - 一致性: 遵循现有的模式和“最小接口,最大细节”的理念。
版本说明
此项目 (@aashari/mcp-server-atlassian-confluence) 遵循语义化版本控制,并独立于其他 @aashari/mcp-server-* 包进行版本管理。