# 通过 MCP 连接

把 Claude Desktop、Claude Code、Cursor、Codex 或其他 MCP 客户端连接到 Oleafly 的本地项目工具。

Oleafly 可以充当 MCP（Model Context Protocol，模型上下文协议）服务器。Claude Desktop、Claude Code、Cursor、Codex 和 Grok CLI 等 MCP 客户端可以读取、编辑、搜索和编译 Oleafly 项目。你不需要在 Oleafly 中填写 AI 提供商的密钥，因为模型由客户端提供。

如果你已经订阅了 Claude（或类似的服务），想让那个聊天应用来驱动 Oleafly，而不必把 API 密钥粘贴到[设置](/docs/ai-setup/)里，就用这个选项。

## 启用

1. 打开 **设置 → 集成 → Oleafly MCP**。
2. 打开 **启用 MCP 服务器** 开关。

服务器只在 Oleafly 进程打开期间运行。它只监听 `127.0.0.1`，绝不监听你的局域网。关闭项目窗口不会停止服务器；关闭 MCP 或退出 Oleafly 才会。

Oleafly 优先使用端口 `5323`（`http://127.0.0.1:5323/mcp`）。如果该端口不可用，服务器会自动绑定另一个空闲的本地端口，并保存下来供下次启动使用。设置中会显示当前使用的 URL。它的重启按钮会尽量复用当前端口，否则选择另一个空闲端口。

## 连接你的客户端

:::tip[无需复制令牌]
`oleafly` 命令有自己的 MCP 服务器，通过标准输入和输出通信。它会自己找到正在运行的应用及其令牌，所以你不用复制 URL 或令牌，也不需要 Node.js。`oleafly mcp config --client claude-desktop` 会打印设置内容；客户端名称有 `claude-code`、`claude-desktop`、`codex`、`cursor` 和 `gemini`。参见[命令行工具](/docs/cli/#connect-an-agent-over-mcp)。
:::

设置中为常见的客户端提供了可直接复制粘贴的代码片段。请复制实时的 URL，因为选中的端口可能不是 `5323`，然后把 `<token>` 替换为设置中的 Bearer 令牌（显示 / 复制）。

### Claude Code

```bash
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"
```

### Claude Desktop

添加到 `claude_desktop_config.json`（通过 `mcp-remote` 的 stdio 桥接，因为 Desktop 偏好 stdio）：

```json
{
  "mcpServers": {
    "oleafly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://127.0.0.1:5323/mcp",
        "--header",
        "Authorization: Bearer <token>",
        "--transport",
        "http-only"
      ]
    }
  }
}
```

### Claude Desktop 扩展

每个版本都附带 `oleafly.mcpb`，这是一个 Claude Desktop 扩展，因此不需要配置文件或令牌。从[最新版本](https://github.com/Oleafly/Oleafly/releases/latest)下载，用 Claude Desktop 打开即可安装。

扩展会启动应用自带的 `oleafly` 命令，并处理 Oleafly 当前打开的项目，所以请保持 Oleafly 运行并开启 MCP 服务器。如果 Claude Desktop 找不到该命令，请在扩展设置中手动选择：macOS 上是 `Oleafly.app/Contents/MacOS` 中的 `oleafly-cli`，Windows 上是 `%LOCALAPPDATA%\Oleafly` 中的 `oleafly-cli.exe`。

MCP Registry 中收录的同一扩展名为 `io.github.Oleafly/oleafly`。

### Cursor / VS Code

在 `.cursor/mcp.json`（或你的客户端的 MCP 配置）中：

```json
{
  "mcpServers": {
    "oleafly": {
      "url": "http://127.0.0.1:5323/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

### Grok CLI

在 `~/.grok/config.toml` 中：

```toml
[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }
```

### Codex CLI

使用 Oleafly 设置中的 **Codex CLI** 代码片段，它提供了连接到正在运行的服务器的 stdio 桥接。把这一项添加到你的 Codex 配置中，并使用 Oleafly 显示的实时 URL 和令牌：

```toml title="~/.codex/config.toml"
[mcp_servers.oleafly]
command = "npx"
args = [
  "-y",
  "mcp-remote@latest",
  "http://127.0.0.1:5323/mcp",
  "--header",
  "Authorization: Bearer <token>",
  "--transport",
  "http-only"
]
```

这个桥接需要 Node.js 和 `npx`。修改客户端的配置后，请重启客户端或重新连接。

如果你想用脚本完成设置，Oleafly 数据目录旁边的 `mcp.json` 文件（在设置中显示）保存着同样的 URL 和令牌。它只在服务器运行期间写入（在 Unix 上权限为 `0600`），服务器停止时会被删除。请像对待其他本地密钥一样对待它。

## 这些工具能做什么

大多数 MCP 工具与应用内助手共用名称和模式。项目发现和路由工具由桌面后端提供。

有项目在应用中打开时，工具会以该项目为目标。有已连接的窗口时，可以用 `list_projects` 和 `open_project` 选择另一个项目。

最后一个窗口关闭之后，后端会继续提供 `read_file`、`list_files` 和 `search_project`。在批准策略允许时，原生的写入、替换、创建和重命名也仍然可用。这些工具只使用应用报告的最后一个项目，如果该项目不再有效，就会拒绝调用。它们绝不会从库中的其他项目里猜测。状态、项目选择、删除、编译、日志、PDF 检查、主题更改和图片工具都需要已连接的窗口。

### 概览

| 工具 | 作用 |
|---|---|
| `get_status` | Oleafly 版本、打开的项目、它的文档引擎、主文档、最近一次编译的状态，以及最近一次编译失败或无法运行的原因 |
| `list_projects` | 项目及其 ID、名称、引擎、类型、主文档、时间戳、颜色、预览状态和导出历史 |
| `open_project` | 按 id 打开项目，让其他工具以它为目标 |
| `list_files` | 项目文件树 |
| `project_map` | 大纲、标签、引用、宏、输入关系图、未解析的引用 |
| `search_project` | 在当前项目中搜索文本 |

### 读取

| 工具 | 作用 |
|---|---|
| `read_file` | 读取项目文件 |
| `get_log` | 最近一次的编译日志 |
| `get_pdf_text` | 从编译出的 PDF 中提取的文本 |
| `verify_pdf_pages` | 根据页面图像或页面文本，检查渲染出的 PDF 页面是否有版面问题 |

`get_pdf_text` 和 `verify_pdf_pages` 读取的是 Oleafly 手头最近的那份 PDF。最近一次编译失败或无法运行时，它们的结果会说明这份 PDF 已经过期以及原因，因为它来自更早的编译，或者是失败的编译留下的不完整的 PDF。最近一次编译无法运行时，`get_log` 也会这样说明，因为这时它的日志来自更早的编译。

### 编辑

| 工具 | 作用 |
|---|---|
| `write_file` | 写入或覆盖文件 |
| `replace_in_file` | 在文件内查找并替换 |
| `create_file` | 创建文件或文件夹 |
| `rename_file` | 重命名或移动路径 |
| `delete_file` | 删除文件或文件夹 |
| `set_main_doc` | 设置编译入口文档 |

### 编译与图片

| 工具 | 作用 |
|---|---|
| `compile` | 把项目编译为 PDF |
| `preview_figure` | 单独渲染一张图片并返回 PNG 图像 |
| `insert_figure` | 把最近预览过的图片插入文档 |
| `load_image` | 从项目中加载图片，用于图片相关工作 |

`compile` 会说明构建是否成功、列出它的错误、说明有没有 PDF，并以日志的最后一部分结尾。构建完成时，它还会报告警告。当构建无法运行、没有完成，或需要源码之外的东西（例如缺少 TeX 安装或某个 Typst 版本）时，结果会给出原因，并指出 Oleafly 在应用中向你提供的修复办法。该工具会请客户端告知你，并且不要改动你的源码。你停止的编译会标记为已停止，所以客户端不会把它当作代码中的错误。Oleafly 自己的助手得到的是同样的结果。

请先调用 `get_status`，了解项目是 LaTeX、Typst 还是 Markdown，然后用该格式编写源码。`preview_figure` 和 `insert_figure` 适用于 LaTeX 和 Typst 项目：

- 在 LaTeX 中，图片是在一个小型独立文档中编译的 TikZ 代码，`insert_figure` 会把它包进 `figure` 环境。
- 在 Typst 中，图片是 Typst 标记，例如 CeTZ 画布或 fletcher 图，用项目的 Typst 版本渲染。`insert_figure` 会把它包进 `#figure`，把标签放在它后面，并把它的 `#import` 行移到它上方。
- 在 Markdown 项目中，两个工具都会返回错误，并且不做任何改动。

`load_image` 适用于所有项目。

### 应用

| 工具 | 作用 |
|---|---|
| `toggle_theme` | 切换浅色 / 深色模式 |

### 技能

| 工具 | 作用 |
|---|---|
| `list_skills` | 列出已安装的技能及其 ID、名称、说明，以及是否已开启 |
| `load_skill` | 加载某个技能的完整说明及其文件列表 |
| `read_skill_file` | 读取技能文件夹中的参考资料或脚本 |

技能工具在连接之后就能使用，不需要打开项目，也不需要 Oleafly 窗口。客户端能看到每一个有效的技能，包括在设置中关闭的：这些开关决定的是 Oleafly 自己的助手使用哪些技能，而不是客户端可以读取什么。改为从文件夹读取技能的代理，可以使用 **设置 → AI 助手 → 技能** 中的 **与此计算机上的其他代理共享技能**。参见[技能](/docs/skills/)。

### 笔记

这些工具在 **设置 → 实验功能** 中的 **笔记** 开启时可用，详见[开启笔记](/docs/notes/#turn-on-notes)。它们作用于你的笔记，而不是当前打开的项目，并且需要一个已连接的窗口。

| 工具 | 作用 |
|---|---|
| `list_knowledge_notes` | 列出你的笔记，最新的在前，附带 ID、标题、标签、关联的项目和简短摘要。可按标签或项目筛选 |
| `search_notes` | 搜索你的笔记，返回 ID、标题、标签、链接和匹配的片段 |
| `read_note_by_id` | 以 Markdown 形式读取一篇笔记，包括它的 front matter |
| `today_note` | 读取今日的每日笔记；如果它还不存在，则返回它将使用的标题 |
| `list_note_tasks` | 列出你笔记中带复选框的任务，最新的笔记在前。可按笔记以及未完成或已完成筛选 |
| `note_backlinks` | 列出链接到某篇笔记的笔记，以及每个链接周围的文字 |
| `append_to_note` | 把 Markdown 添加到一篇笔记或今日的每日笔记的末尾 |
| `edit_note_section` | 重写笔记中某个标题下的部分，或在它的末尾添加内容 |
| `create_note` | 创建一篇笔记，包含标题、Markdown、标签和关联的项目 |

`append_to_note` 和 `edit_note_section` 不会直接写入笔记。它们的更改会作为建议显示在笔记中，直到你在 Oleafly 中接受。`create_note` 要等你在 Oleafly 中批准；`append_to_note` 在必须先创建今日的每日笔记时也一样。在 **信任此连接** 下，创建笔记不会询问。通过协作服务器共享的笔记可以读取，但不能用这种方式更改。**只读** 会移除这三个会更改笔记的工具。

## 批准与安全

许多 MCP 客户端会在调用工具之前询问。Oleafly 还会应用你在 **设置 → 集成 → Oleafly MCP** 中选择的策略：

- **确认每次更改** 是默认值。有应用窗口连接时，写入、重命名和删除会显示批准卡片。没有窗口时，这些操作会被拒绝，因为没有地方可以显示卡片。
- **自动批准编辑，删除需确认** 让写入和重命名在后端运行。删除仍然需要已连接的窗口来确认。
- **信任此连接** 让后端的写入和重命名无需 Oleafly 提示即可运行。删除仍然需要已连接的窗口。只有在你信任该客户端及其自身的批准控制时，才使用这个策略。

还有两个开关作为后盾：

- **只读**（单独的开关）会把会修改内容的工具从 `tools/list` 中完全移除，所以无论上面的策略是什么，外部应用都只能读取和编译，而无法修改文件。
- **Bearer 令牌**：一个 256 位的随机值，存放在 `~/.oleafly/` 下经过认证的加密本地存储中。重新生成它可以使旧的客户端失效。一般的配置读取绝不会暴露这个令牌。只有正在运行的服务器的连接控件才能在设置中显示它。

此外还有两条不需要你配置的不变规则：

- **仅限本机**：绑定地址是 `127.0.0.1`。带有浏览器 `Origin` 头的请求会被拒绝，而且 `Host` 必须是回环地址。
- **限定在项目内**：后端的文件工具接受项目相对路径，并把规范化路径限定在应用报告的项目之内。工具调用不能提供另一个项目 ID，也不能让后端选择库中的其他项目。

## 观察它的工作

有窗口连接时，**MCP 活动** 标签页会记录传入的调用。最后一个窗口关闭之后，后端调用可以继续，但在窗口重新连接之前，不会有活动面板或批准卡片。

## 为什么浏览器中的 claude.ai 无法连接

云端聊天服务无法访问你机器上的 `127.0.0.1`。请改用 **Claude Desktop**（或 Claude Code、Cursor 等）。不要把 MCP 端口通过隧道暴露到公共互联网：那样会让任何拿到 URL 的人都能编辑和删除你本地的项目文件。

## 故障排查

| 现象 | 可以尝试 |
|---|---|
| 有些工具不可用 | 图片预览和其他仅限 UI 的工具需要 Oleafly 窗口。打开应用和项目，然后重试 `tools/list`。 |
| 端口不再是 `5323` | 首选端口不可用，所以 Oleafly 选了一个空闲的端口。请从设置中复制实时的 URL。 |
| HTTP 401 | 令牌不匹配（例如在重新生成之后）。把新的令牌复制到客户端中。 |
| HTTP 403 | 客户端发送了 `Origin` 头或非回环的 `Host`。请使用原生的 MCP 客户端，而不是浏览器标签页。 |
| 调用超时 | 每次工具调用最多等待 **5 分钟**（300 秒），用于编译或等你点击批准。请批准或拒绝待处理的卡片，或者重试。编译可能需要更久，Quarto 或 Calepin 笔记本最长可达一小时。调用超时之后，它仍会在 Oleafly 中继续运行，而需要 Oleafly 窗口的工具会等待它，所以请让它完成后再重试。 |
| `compile` 返回的是原因而不是错误 | 构建无法运行，例如因为没有安装 TeX。请使用 Oleafly 在应用中提供的修复办法，例如安装 TinyTeX，然后再次编译。 |
| 无法连接 | Oleafly 必须在运行，并且已启用 MCP。这个服务器会在你退出时停止；如果要在应用关闭时使用项目工具，请把客户端连接到 `oleafly mcp`。 |

## 为 Oleafly 添加外部工具

![设置 → AI 助手 → MCP。添加服务器、浏览注册表，或从其他工具导入配置。](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-mcp-dark-window-v2.png#view=519,89,883,568)

要给内置助手更多工具，请打开 **设置 → AI 助手 → MCP**。

- **浏览注册表** 来查找服务器并查看其设置。
- **从其他工具导入** 来选择现有的服务器配置。导入之前，请先查看选中的条目。
- **添加服务器** 来自己输入一个服务器，然后验证连接。

已连接的服务器会把它们的工具提供给助手。你可以在同一个页面查看连接状态，以及启用或停用服务器。凭据和命令属于各个服务器的配置；连接新服务器之前，请先查看它们。

alphaXiv 也是作为 MCP 服务器连接的，但你需要在 **设置 → 集成 → alphaXiv** 中用 API 密钥来设置，而不是在这里。连接之后，它会以 **alphaXiv** 的名称出现在这个列表中。具体步骤参见[连接研究资源](/docs/integrations/research-sources/#alphaxiv)。

## 手动配置外部服务器

![添加服务器 → 表单。选择本地命令或远程 URL，填写连接字段，然后使用添加并验证。](https://cdn.oleafly.com/images/screenshots/desktop/docs/mcp-add-server-dark-window-v2.png#view=670,228,578,625)

在 **设置 → AI 助手 → MCP** 下，选择 **添加服务器**。本地服务器通过 stdio 运行一条命令；远程服务器连接到一个 URL。JSON 表单使用 Oleafly 的服务器格式：

```json title="本地服务器配置"
{
  "name": "Research tools",
  "enabled": true,
  "transport": "stdio",
  "command": "your-mcp-server",
  "args": ["--stdio"],
  "env": {}
}
```

把命令和参数替换为你所安装的服务器文档中给出的内容。环境变量的值放在 `env` 对象中。

```json title="远程服务器配置"
{
  "name": "Research service",
  "enabled": true,
  "transport": "remote",
  "url": "https://your-server.example/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}
```

把示例 URL 和令牌替换为该服务的连接信息。使用 **验证** 检查连接，然后查看服务器提供的工具。在它所在的行上启用或停用服务器。用它的编辑操作更改配置，用它的移除操作断开连接。

## 导入现有的 MCP 配置

选择 **从其他工具导入**，查看发现的配置，并选中你想要的服务器。导入之前，请先查看可执行文件路径、环境变量、URL 和凭据。这只会导入连接设置；它不会为你安装服务器的可执行文件。

## 试试这个连接

1. 在 Oleafly 中打开一个用来练习的小项目。
2. 使用从应用复制的代码片段连接外部客户端。
3. 让客户端调用 `get_status` 并列出项目文件。
4. 让它读取主文档，并建议修改标题。
5. 在批准写入之前，先在 Oleafly 中查看这项操作。
6. 编译并检查 PDF。

对于 Oleafly 内部已连接的外部工具，先从该服务器支持的一个简单的只读请求开始，并在聊天中查看生成的工具卡片。
