MCP 连接 Confluence/知识库：让 AI 读取团队文档的方法

团队文档散落在 Confluence 里，AI Agent 想读取却只能靠人工粘贴——这个场景在不少开发团队里已经成了效率瓶颈。MCP（Model Context Protocol）正好能打通这一环：让 Claude Code、Codex、Hermes Agent 这类工具直接读取 Confluence 页面内容，实现上下文感知的自动化工作流。本文以 VPS 部署为背景，手把手配置 MCP Server 连接 Confluence 知识库，让 AI 能实时拉取团队文档，不再依赖手动导出。

MCP 连接 Confluence 知识库的实战价值

传统做法是把 Confluence 页面导出为 PDF 或 Markdown，再喂给 AI。问题是文档一多就乱，更新后还得重新同步。MCP 连接 Confluence 后，AI Agent 可以直接通过 API 搜索、读取、甚至解析页面结构，省去中间搬运步骤。适合的场景包括：

• 开发者在 Claude Code 中直接引用需求文档、接口说明。

• n8n 自动化工作流中，触发 Confluence 页面变更后自动更新 AI 知识库。

• Hermes Agent 根据最新文档生成代码或测试用例。

这一切的前提是 VPS 上能跑通 MCP Server，并正确配置 Confluence API。

准备工作：API Key、空间权限与 Docker 环境

在 VPS 上部署前，先确认三个条件：

1. Confluence API Token

登录 Confluence（Cloud 版），进入个人设置 → API Token → 创建新 Token。记下 token 和你的 Confluence 域名（例如 `your-domain.atlassian.net`）。如果你用的是自托管 Confluence（Server/Data Center），需要管理员提供 Personal Access Token（PAT）。

2. 空间权限

AI Agent 只能读取它有权访问的空间。确保你使用的账号至少对目标空间有“查看”权限。如果页面设置了限制，API 会返回 403。

3. VPS 上的 Docker 环境

MCP Server 推荐用 Docker 部署，避免依赖冲突。VPS 上先安装 Docker：

sudo apt update && sudo apt install docker.io -y
sudo systemctl enable docker && sudo systemctl start docker
docker –version

内存建议至少 1GB，跑 MCP Server 本身不重，但如果你同时运行 AI Agent（如 Claude Code），建议 2GB 以上。

MCP Server 配置步骤（以连接 Confluence 为例）

这里以开源项目 `mcp-server-confluence`（官方或社区维护版本）为例，演示如何让 Claude Code 读取团队文档。

1. 拉取 MCP Server 镜像

docker pull ghcr.io/your-org/mcp-server-confluence:latest

如果找不到官方镜像，可以用 Python 版实现（见后文兼容方案）。

2. 编写 Docker Compose 配置

创建 `docker-compose.yml`：

yaml
version: '3.8'
services:
mcp-confluence:
image: ghcr.io/your-org/mcp-server-confluence:latest
container_name: mcp-confluence
environment:
– CONFLUENCE_URL=https://your-domain.atlassian.net
– CONFLUENCE_USER=your-email@example.com
– CONFLUENCE_TOKEN=your-api-token
– MCP_PORT=3100 # MCP 服务监听端口
ports:
– "3100:3100"
restart: unless-stopped

安全提醒：API Token 是敏感信息，不要直接写死在 docker-compose.yml 里。生产环境建议用 Docker secrets 或环境变量文件（`.env`），并设置文件权限 600。

3. 启动服务并验证

docker-compose up -d
docker logs mcp-confluence

如果日志出现 `MCP server started on port 3100`，说明启动成功。用 curl 测试 MCP 协议是否正常：

curl -X POST http://localhost:3100/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"list_tools","id":1}'

返回包含 `tools` 列表（如 `search_pages`、`get_page_content`）即成功。

4. 在 Claude Code 中配置 MCP 工具

Claude Code 的配置文件（通常位于 `~/.claude/config.json`）中添加：

json
{
"mcpServers": {
"confluence": {
"type": "http",
"url": "http://your-vps-ip:3100/mcp"
}
}
}

重启 Claude Code，输入 `/mcp` 看到 `confluence` 工具即生效。之后在对话中直接说“搜索 Confluence 上关于‘部署指南’的页面”，AI 会自动调用 MCP 读取。

5. 兼容方案：Python 版 MCP Server

如果 Docker 镜像不可用，可以用 Python 手动实现一个轻量 MCP Server（依赖 `atlassian-python-api`）：

pip install mcp atlassian-python-api

然后写一个脚本暴露 `search_pages` 和 `get_page_content` 两个工具。具体代码可参考官方 MCP 文档的 Confluence 示例。这种方式适合自定义需求，但需要额外维护。

常见踩坑与日志排查

端口放行

VPS 防火墙没放行 MCP 端口（本例 3100），导致 AI Agent 无法连接。检查：

sudo ufw status
sudo ufw allow 3100/tcp

如果是云服务商安全组，记得在控制台添加入站规则。

API Token 权限不足

出现 `403 Forbidden` 时，先确认 token 是否有效，再检查 Confluence 空间权限。可以临时用管理员账号测试，验证通过后改用受限账号。

页面内容太长导致超时

Confluence 页面可能包含大量表格或附件，MCP Server 默认读取超时时间可能不够。在 docker-compose 中增加 `MCP_TIMEOUT=30000`（毫秒）或调整 AI Agent 的超时配置。

MCP 协议版本不匹配

Claude Code 或 Codex 使用的 MCP 版本可能和 Server 不兼容。查看 Server 日志，如果有 `unsupported method` 错误，升级 Server 或降级 Client。以官方仓库文档为准。

老鸟叮嘱

1.不要用 root 跑 MCP Server。创建单独用户 `mcp`，用 `docker-compose` 以非 root 用户运行。如果被攻击，root 权限意味着整个 VPS 沦陷。
2.MCP 端口不要裸露公网。只允许本地或内网访问，或者用 Nginx 反向代理加 Basic Auth。直接暴露 3100 端口等于把 Confluence 内容开放给互联网。
3.区分 API 调用型和本地模型型。MCP 连接 Confluence 属于 API 调用型，AI 模型本身不存储文档，只是实时查询。如果你的 VPS 同时跑本地模型（如 Ollama），注意内存分配。
4.生产环境加缓存。如果 AI Agent 频繁读取同一页面，MCP Server 可以加 Redis 缓存，减少 Confluence API 调用次数，避免触发限流。

FAQ

Q: MCP 连接 Confluence 需要什么配置的 VPS？
A: 最低 1 核 1GB 内存，能跑 Docker 即可。如果同时运行 Claude Code 或 Codex，建议 2 核 4GB。

Q: 自托管 Confluence 能用 MCP 吗？
A: 能。需要确保 Confluence 有 REST API 可用（Server 版默认开启），并配置 Personal Access Token 或 Basic Auth。

Q: AI Agent 能修改 Confluence 页面吗？
A: 取决于 MCP Server 暴露的工具。本文示例只读，如果你需要写操作（如创建页面），需要额外配置写权限，并严格限制 AI 的修改范围。

Q: MCP Server 日志里出现 `connection refused` 是什么原因？
A: 通常是端口未放行或服务未启动。先 `docker ps` 确认容器运行，再 `curl localhost:3100` 测试本地连通性。

Q: 可以用 n8n 替代 MCP Server 吗？
A: n8n 也能调用 Confluence API，但 MCP 是标准协议，能让多个 AI Agent 统一接入。如果你只用 n8n，可以跳过 MCP，直接用 n8n HTTP 节点。

Q: 如何保证 API Token 安全？
A: 使用 Docker secrets 或环境变量文件，文件权限设为 600。不要在代码仓库中明文提交 token。

让 AI 读取团队文档并不是什么黑科技，难点在于配置细节和权限管理。MCP 标准化了 Agent 与知识库的交互方式，一旦跑通，后续扩展到其他工具（如 GitHub、Jira）也只是改几行配置的事。主机选之前有不少读者问“AI 怎么读公司内部的 Confluence”，这套方案已经帮几个团队落地了，希望能给你省下试错时间。

—

**相关阅读：**

– [VPS部署AI工具100讲：AI Agent、Codex、Claude Code、Hermes Agent、Ollama与自动化工作流实战教程](https://www.zhujixuan.com/jishujiaocheng/9606.html)
– [Codex、Claude Code、OpenClaw、Hermes Agent、Ollama、n8n 分别适合什么场景](https://www.zhujixuan.com/jishujiaocheng/9759.html)
– [n8n VPS 部署教程：搭建自己的自动化工作流平台](https://www.zhujixuan.com/jishujiaocheng/9892.html)