跳转到内容
Oleaflyv0.4.12

连接

把 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 密钥粘贴到设置里,就用这个选项。

MCP 的两个方向一个方向是:你电脑上的 MCP 客户端,例如 Claude Desktop、Cursor 或 Codex,用 Bearer 令牌连接到 127.0.0.1 上的 Oleafly MCP 服务器。它可以读取、编辑和编译项目,哪些更改需要等你确认,由你的审批策略决定。另一个方向是:Oleafly 内置的助手使用你添加的 MCP 服务器提供的工具,可以是运行一条命令的本地服务器,也可以是位于某个 URL 的远程服务器。你的 MCP 客户端使用 Oleafly 的工具Oleafly 的助手使用其他 MCP 服务器MCP 客户端Claude Desktop,Cursor, CodexOleafly MCP仅限 127.0.0.1项目读取、编辑、编译Bearer 令牌审批助手Oleafly 内置本地服务器运行一条命令远程服务器连接到某个 URLMCP 的两个方向一个方向是:你电脑上的 MCP 客户端,例如 Claude Desktop、Cursor 或 Codex,用 Bearer 令牌连接到 127.0.0.1 上的 Oleafly MCP 服务器。它可以读取、编辑和编译项目,哪些更改需要等你确认,由你的审批策略决定。另一个方向是:Oleafly 内置的助手使用你添加的 MCP 服务器提供的工具,可以是运行一条命令的本地服务器,也可以是位于某个 URL 的远程服务器。你的 MCP 客户端使用 OleaflyOleafly 的助手使用服务器MCP 客户端Claude Desktop, CursorOleafly MCP仅限 127.0.0.1项目读取、编辑、编译Bearer 令牌审批助手Oleafly 内置本地服务器运行一条命令远程服务器连接到某个 URL
你电脑上的 MCP 客户端通过 127.0.0.1 和令牌使用 Oleafly 的项目工具。反过来,Oleafly 的助手也可以使用你添加的 MCP 服务器提供的工具。
  1. 打开 设置 → 集成 → Oleafly MCP。
  2. 打开 启用 MCP 服务器 开关。

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

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

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

终端窗口
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"

添加到 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"
]
}
}
}

每个版本都附带 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/mcp.json(或你的客户端的 MCP 配置)中:

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

在 ~/.grok/config.toml 中:

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

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

~/.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_statusOleafly 版本、打开的项目、它的文档引擎、主文档、最近一次编译的状态,以及最近一次编译失败或无法运行的原因
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 活动 标签页会记录传入的调用。最后一个窗口关闭之后,后端调用可以继续,但在窗口重新连接之前,不会有活动面板或批准卡片。

云端聊天服务无法访问你机器上的 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。
设置 → AI 助手 → MCP。添加服务器、浏览注册表,或从其他工具导入配置。
设置 → AI 助手 → MCP。添加服务器、浏览注册表,或从其他工具导入配置。 打开完整截图

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

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

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

alphaXiv 也是作为 MCP 服务器连接的,但你需要在 设置 → 集成 → alphaXiv 中用 API 密钥来设置,而不是在这里。连接之后,它会以 alphaXiv 的名称出现在这个列表中。具体步骤参见连接研究资源。

添加服务器 → 表单。选择本地命令或远程 URL,填写连接字段,然后使用添加并验证。
添加服务器 → 表单。选择本地命令或远程 URL,填写连接字段,然后使用添加并验证。 打开完整截图

在 设置 → 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 和令牌替换为该服务的连接信息。使用 验证 检查连接,然后查看服务器提供的工具。在它所在的行上启用或停用服务器。用它的编辑操作更改配置,用它的移除操作断开连接。

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

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

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

图片预览

无法加载 AI 回答

请重试,或搜索文档。