Confluence MCP Server

让 Claude Code 能直接读取 Confluence 内部文档。

它能做什么

• get_page — 给一个页面 ID 或完整 URL，返回页面内容（转成 Markdown），并自动下载页面内的图片，让 Claude 能看懂产品图等视觉内容
• search_pages — 输入关键词，返回匹配的页面列表

安装

cd ~/confluence-mcp
npm install
npm run build

如果 npm install 报网络错误，改用公共源： npm install --registry=https://registry.npmjs.org/

配置

第一步：填写站点信息

在项目根目录创建 sites.json，填上你的站点信息：

[
  {
    "name": "rd",
    "baseUrl": "https://your-confluence.example.com",
    "username": "你的用户名",
    "password": "你的密码"
  }
]

sites.json 已加入 .gitignore，不会被提交到 git。

第二步：接入 Claude Code

编辑 ~/.claude.json，在 mcpServers 里加入：

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["/Users/你的用户名/confluence-mcp/dist/index.js"],
      "env": {}
    }
  }
}

args 里的路径改成你自己机器上的实际路径。

第三步：重启 Claude Code

重启后，Claude Code 会自动加载 get_page 和 search_pages 两个工具。

多站点

如果你有多个 Confluence 站点，在 sites.json 里加就行：

[
  {
    "name": "rd",
    "baseUrl": "https://rd.example.com",
    "username": "alice",
    "password": "xxx"
  },
  {
    "name": "wiki",
    "baseUrl": "https://wiki.example.com",
    "username": "bob",
    "password": "yyy"
  }
]

然后在 ~/.claude.json 的 env 里指定用哪个：

"env": { "CONFLUENCE_SITE": "wiki" }

不设的话默认用第一个。

使用

配置好重启 Claude Code 后，直接在对话里说：

读一个页面：

帮我看看这个页面：https://rd.dtsphere.com/pages/viewpage.action?pageId=90394821 帮我读页面 90394821

搜索：

搜一下关于「部署流程」的文档

多站点时指定站点：

去 wiki 站点搜「接口规范」

Claude 会自动调用工具，不需要手动指定工具名。

关于图片

get_page 默认会下载页面里的图片（产品图、流程图等）一起返回。

• 单页最多取 10 张图，自动过滤表情、图标等装饰性图片
• 只想看文字、不想下图时，可以让 Claude 跳过：

  读页面 90394821，不用下图

注意：命令行版（CLI）的 Claude 没有视觉能力，看不了图片内容。 网页版、桌面版能直接看图；CLI 下要分析图片，用下面的视觉分析。

让 CLI 也能分析图片（视觉分析）

CLI 看不了图时，可以让工具先调用视觉模型把图片解读成文字，再返回：

读页面 90394821 的 2.2 章节，分析里面的图片

工具会把图片喂给视觉模型，把"页面长什么样、有哪些字段和交互"的分析结论作为文字一并返回，CLI 就能基于这段文字继续工作。

• 视觉分析走 ~/.claude.json 里配置的同一套 API（ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL）
• 分析用哪个模型，按优先级取：CONFLUENCE_VISION_MODEL（图片分析专用）→ ANTHROPIC_MODEL（通用）→ 回退默认
• claude --model haiku 或 /model 切换不影响图片分析模型——主体模型和分析模型是两条独立链路（详见下方实现原理）
• 想单独指定分析模型，在 server 的 env 里加 CONFLUENCE_VISION_MODEL，重启生效
• 配合 sections 只分析某章节的图，又快又省

分段读大页面

页面内容很长时（如大型需求文档），可以让 Claude 只读某几章，避免上下文撑爆：

读页面 90394821，只看第 2 到第 3 章 读页面 90394821，只看 sections 2-3.2.1

sections 参数裁的是正文，图片也只取那几章里的，两者同步缩减。

建议用法： 先用 search_pages 定位页面，再分章节逐段读，每次只给 Claude 当前要分析的那段内容。

文件位置一览

文件	作用
~/confluence-mcp/sites.json	站点配置（你维护，不进 git）
~/confluence-mcp/dist/index.js	MCP server 实际运行的文件
~/.claude.json	Claude Code 配置，指向上面的 dist

实现原理

这个 server 的本质是一个只读的翻译层：Claude 连不上你内网的 Confluence，server 替它调 API，把结果转成 Claude 能消化的 Markdown + 图片 / 图片分析。

整体架构

一个文件一个职责，各自可独立测试：

Claude Code (CLI / 桌面 / 网页)
      │  MCP 协议 (stdio)
      ▼
  index.ts        启动入口，建 server，接 stdio
      │
  tools.ts        注册 2 个工具，编排整个流程
      │
      ├── confluence.ts   调 Confluence REST API（带认证）
      ├── url.ts          解析 pageId / 各种 URL 形式
      ├── sections.ts     按章节编号裁剪正文
      ├── html.ts         HTML → Markdown
      ├── images.ts       从 HTML 抽图片链接
      └── vision.ts       调视觉模型分析图片
  config.ts         读 sites.json，管多站点配置

get_page 的完整数据流

一次 get_page 调用，内部依次发生：

1. 解析引用（url.ts）— 用户给的可能是纯数字 90387185、完整 URL、或 /display/空间/标题，统一解析成 pageId 或「空间+标题」。
2. 调 API 取页面（confluence.ts）— 带 Basic 认证请求 /rest/api/content/{id}?expand=body.view，拿到渲染后的 HTML。401/404 统一转中文错误。
3. 按章节裁剪（sections.ts，可选）— 指定 sections 时，根据标题里的自动编号（<span class="nh-number">2.2.</span>）把正文切到指定区间。这是省上下文的关键。
4. HTML 转 Markdown（html.ts）— 用 turndown 转成干净的 Markdown。
5. 处理图片（images.ts + confluence.ts）— 从正文 HTML 抽出附件图链接（过滤表情/图标），带认证下载转 base64。图片从裁剪后的 HTML 抽取，所以只看某章节时图片也只取那章的，正文和图同步缩减。
6. 视觉分析（vision.ts，可选）— 开启 analyzeImages 时，server 自己调一次视觉模型把图片解读成文字，追加到返回里，让没有视觉能力的 CLI 也能用上图片内容。

为什么 /model 切换不影响图片分析

MCP server 是 Claude Code 启动时 fork 出的独立子进程：

终端
  ├─ Claude Code 主进程      ← /model 只切这里（跟你对话的模型）
  └─ confluence MCP 子进程    ← vision.ts 用自己的 env 调模型

/model 改的是主进程内存里的设置，不会传播到已经跑起来的子进程。vision.ts 调模型走的是它自己发起的全新 API 请求，模型名来自子进程启动时的环境变量，跟主体当前选什么模型没有通信渠道。所以图片分析模型只能通过 server 的 env（CONFLUENCE_VISION_MODEL 等）控制。

关键设计决策

• 图片下载失败返回 null 而非抛错 — 一页十几张图，一张挂了不该拖垮整页。
• vision client 懒加载 — 缺 token 时只在真正分析图片时才报错，不影响纯文本的 get_page / search_pages。
• 只读 — 全程只有 GET，没有任何写/改/删 Confluence 的能力。
• 凭据隔离 — 账密放 sites.json，已进 .gitignore。

开发

npm test       # 跑单元测试
npm run build  # 重新编译