连接
通过 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 密钥粘贴到设置里,就用这个选项。
- 打开 设置 → 集成 → Oleafly MCP。
- 打开 启用 MCP 服务器 开关。
服务器只在 Oleafly 进程打开期间运行。它只监听 127.0.0.1,绝不监听你的局域网。关闭项目窗口不会停止服务器;关闭 MCP 或退出 Oleafly 才会。
Oleafly 优先使用端口 5323(http://127.0.0.1:5323/mcp)。如果该端口不可用,服务器会自动绑定另一个空闲的本地端口,并保存下来供下次启动使用。设置中会显示当前使用的 URL。它的重启按钮会尽量复用当前端口,否则选择另一个空闲端口。
连接你的客户端
标题为“连接你的客户端”的部分设置中为常见的客户端提供了可直接复制粘贴的代码片段。请复制实时的 URL,因为选中的端口可能不是 5323,然后把 <token> 替换为设置中的 Bearer 令牌(显示 / 复制)。
Claude Code
标题为“Claude Code”的部分claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"Claude Desktop
标题为“Claude Desktop”的部分添加到 claude_desktop_config.json(通过 mcp-remote 的 stdio 桥接,因为 Desktop 偏好 stdio):
{ "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 扩展
标题为“Claude Desktop 扩展”的部分每个版本都附带 oleafly.mcpb,这是一个 Claude Desktop 扩展,因此不需要配置文件或令牌。从最新版本 (在新标签页中打开)下载,用 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 / VS Code”的部分在 .cursor/mcp.json(或你的客户端的 MCP 配置)中:
{ "mcpServers": { "oleafly": { "url": "http://127.0.0.1:5323/mcp", "headers": { "Authorization": "Bearer <token>" } } }}Grok CLI
标题为“Grok CLI”的部分在 ~/.grok/config.toml 中:
[mcp_servers.oleafly]url = "http://127.0.0.1:5323/mcp"headers = { Authorization = "Bearer <token>" }Codex CLI
标题为“Codex CLI”的部分使用 Oleafly 设置中的 Codex CLI 代码片段,它提供了连接到正在运行的服务器的 stdio 桥接。把这一项添加到你的 Codex 配置中,并使用 Oleafly 显示的实时 URL 和令牌:
[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 助手 → 技能 中的 与此计算机上的其他代理共享技能。参见技能。
这些工具在 设置 → 实验功能 中的 笔记 开启时可用,详见开启笔记。它们作用于你的笔记,而不是当前打开的项目,并且需要一个已连接的窗口。
| 工具 | 作用 |
|---|---|
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 无法连接
标题为“为什么浏览器中的 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 添加外部工具
标题为“为 Oleafly 添加外部工具”的部分
要给内置助手更多工具,请打开 设置 → AI 助手 → MCP。
- 浏览注册表 来查找服务器并查看其设置。
- 从其他工具导入 来选择现有的服务器配置。导入之前,请先查看选中的条目。
- 添加服务器 来自己输入一个服务器,然后验证连接。
已连接的服务器会把它们的工具提供给助手。你可以在同一个页面查看连接状态,以及启用或停用服务器。凭据和命令属于各个服务器的配置;连接新服务器之前,请先查看它们。
alphaXiv 也是作为 MCP 服务器连接的,但你需要在 设置 → 集成 → alphaXiv 中用 API 密钥来设置,而不是在这里。连接之后,它会以 alphaXiv 的名称出现在这个列表中。具体步骤参见连接研究资源。
手动配置外部服务器
标题为“手动配置外部服务器”的部分
在 设置 → AI 助手 → MCP 下,选择 添加服务器。本地服务器通过 stdio 运行一条命令;远程服务器连接到一个 URL。JSON 表单使用 Oleafly 的服务器格式:
{ "name": "Research tools", "enabled": true, "transport": "stdio", "command": "your-mcp-server", "args": ["--stdio"], "env": {}}把命令和参数替换为你所安装的服务器文档中给出的内容。环境变量的值放在 env 对象中。
{ "name": "Research service", "enabled": true, "transport": "remote", "url": "https://your-server.example/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" }}把示例 URL 和令牌替换为该服务的连接信息。使用 验证 检查连接,然后查看服务器提供的工具。在它所在的行上启用或停用服务器。用它的编辑操作更改配置,用它的移除操作断开连接。
导入现有的 MCP 配置
标题为“导入现有的 MCP 配置”的部分选择 从其他工具导入,查看发现的配置,并选中你想要的服务器。导入之前,请先查看可执行文件路径、环境变量、URL 和凭据。这只会导入连接设置;它不会为你安装服务器的可执行文件。
试试这个连接
标题为“试试这个连接”的部分- 在 Oleafly 中打开一个用来练习的小项目。
- 使用从应用复制的代码片段连接外部客户端。
- 让客户端调用
get_status并列出项目文件。 - 让它读取主文档,并建议修改标题。
- 在批准写入之前,先在 Oleafly 中查看这项操作。
- 编译并检查 PDF。
对于 Oleafly 内部已连接的外部工具,先从该服务器支持的一个简单的只读请求开始,并在聊天中查看生成的工具卡片。