Nelson MCP — LibreOffice

Nelson MCP

一款 LibreOffice 扩展，可将文档变成 MCP 服务。外部 AI 客户端通过 HTTP 连接，并可完整使用文档工具——读取、编辑、导航、格式设置等。

适用于所有兼容 MCP 的客户端：Claude Code、OpenCode、Goose、ollmcp 等。

工作原理

Nelson MCP 在 LibreOffice 内部运行 HTTP 服务，并使用 Model Context Protocol。AI Agent 连接到它，并使用工具与打开的文档交互——无需复制粘贴，也无需导出文件。

┌─────────────────┐     HTTP/MCP     ┌────────────────┐
│  AI Client      │ ───────────────► │  LibreOffice   │
│  (Claude Code,  │    tools/call    │  + Nelson MCP  │
│  OpenCode…)     │ ◄─────────────── │                │
└─────────────────┘   tool results   └────────────────┘

效果展示

Agent 在空白的 Writer 文档中逐次调用工具，写出一份季度报告：

完成后的报告：内容为 Markdown，使用 style_set 设置标题颜色，带底纹的表格、Page {page} of {pages} 页脚，以及招聘相关行上的一条批注。Nelson MCP 侧边栏会记录每次调用。选择一条调用即可查看调用方、状态、耗时和参数。

所有设置都位于 工具 > 选项 > Nelson。例如，HTTP 页面可设置端口、绑定地址和访问令牌：

功能

• 145 个文档工具——读取内容、编辑文本、管理样式、插入图像、处理表格、图表、条件格式、超链接、修订、页眉/页脚、导航标题、搜索等。工具列表会根据当前文档类型筛选，因此客户端只会看到适用的工具（Writer 文档有 97 个，Calc 有 50 个）
• 可自行配置的 Agent——启用配置 API 后，Agent 可自行读取和更改 Nelson 的设置（读取限制、交换格式、其所做更改的名称），而保护你的设置仍由“选项”保留。参见让 Agent 配置 Nelson
• 自定义 MCP 端点——仅公开 Agent 所需的工具。可使用内置预设（minimal、writer-edit、writer-read、calc、gallery），也可创建自己的筛选端点
• Writer、Calc、Draw、Impress——工具会适配当前文档类型
• Calc =PROMPT()——直接在电子表格单元格中调用大模型
• 内置启动器——只需单击一下，即可直接从 LibreOffice 启动 Claude Code、Gemini CLI 或 OpenCode。Nelson 会自动处理 MCP 配置、提示词注入和工作目录设置
• AI 图像生成——使用 Stable Diffusion（A1111/Forge）、OpenAI 或 AI Horde，根据文本提示生成和编辑图像。可一键检测/安装/启动 Automatic1111
• 适合初学者的设置流程——所有工具都附带安装按钮、现有安装的自动检测和引导式配置。无需手动编辑配置文件
• 隧道——通过 ngrok、Cloudflare、bore 或 Tailscale 在外部公开 MCP 服务，并使用访问令牌保护
• SSL——可选 HTTPS，并自动生成证书
• 模块化——每项功能都是独立模块，拥有自己的配置、服务和工具

安装

1. 从发布页面下载最新的 .oxt
2. 在 LibreOffice 中：工具 > 扩展管理器 > 添加
3. 重启 LibreOffice
4. MCP 服务会自动启动（默认地址：http://localhost:8766/mcp）

快速开始

安装后，将 MCP 客户端指向服务：

{
  "mcpServers": {
    "nelson": {
      "type": "http",
      "url": "http://localhost:8766/mcp"
    }
  }
}

在 LibreOffice 中打开文档，然后让 AI 客户端读取或编辑它。

**面向 AI Agent：**参阅 QUICKSTART.md——这是一份分步指南，介绍 LLM Agent 如何发现文档、浏览文档结构并有效使用工具。

让 Agent 配置 Nelson

Agent 不必停下来请你打开“选项”。启用配置 API后，它就能通过同一个 HTTP 服务自行读取和更改 Nelson 的设置，且更改会立即生效。例如，它可以：

• 在处理长文档前提高读取上限；
• 切换到 HTML，以改写格式复杂的文档；
• 用自己的名字标记它跟踪的修订。

在工具 > 选项 > Nelson > Http > 启用配置 API中启用，然后：

# Read one setting, a module, or everything
curl 'http://localhost:8766/api/config?key=writer.max_content_chars'
curl 'http://localhost:8766/api/config?module=writer'

# Change several at once
curl -X POST http://localhost:8766/api/config \
     -H 'Content-Type: application/json' \
     -d '{"writer.max_content_chars": 200000, "writer.change_author": "AI agent"}'

设置访问令牌后，添加 -H 'Authorization: Bearer <token>'。

该 API 可调整 Nelson 的行为，但无法更改保护你的设置。以下设置仅限在选项中更改，触及这些设置的请求会被拒绝，并返回 403，且不会进行任何更改：

• http.*：令牌、地址、允许的源、SSL，以及配置 API 开关本身；
• tunnel.* 和 debug.*；
• launcher.*：Nelson 运行的命令；
• *.instances：工具可以访问的文件夹，以及 AI 提供商的端点和密钥；
• core.force_track_changes。

令牌和 API 密钥等机密信息在读取时会显示为 ***。

安全

任何能够与 Nelson 通信的人，都可以读取和编辑 LibreOffice 中打开的所有文档，也可以打开账户有权读取的任何文件。以下措施可以防止他人访问：

情况	保护措施
默认：仅限本机	服务绑定到 localhost。本机上的 MCP 客户端无需额外配置。
浏览器中的网页	请求会被拒绝。你访问的网页无法调用 localhost:8766：除非你在允许的浏览器源中列出该源，否则浏览器源会被拒绝。
已设置访问令牌	每个请求都必须携带令牌——使用 Authorization: Bearer <token>，或者对于无法设置请求头的客户端，使用 ?token=<token>。内置启动器会自动传递令牌。
可通过网络或隧道访问	Nelson 拒绝绑定到 localhost 以外的地址，也拒绝启动隧道，直到设置令牌为止。

在选项 > Nelson MCP > HTTP > 访问令牌中设置令牌；更改无需重启即可生效。配置 API 无法更改该令牌或任何其他保护设置（见上文），但仍可读取和更改其余设置：在可从其他位置访问的计算机上，请关闭配置 API 和调试 API。

通过隧道公开 Nelson 之前，请阅读 docs/howto/connect-chatgpt-tailscale.md 顶部的警告。

模块

约 30 个模块；主要模块如下：

模块	说明
core	文档访问、配置、事件、格式设置
doc	所有文档类型通用的工具——打开、保存、关闭、导出、打印、撤销/重做、超链接
writer	内容编辑、批注、样式、表格、图像、页眉/页脚、修订跟踪
writer.nav	标题树、书签、邻近导航
writer.index	使用 Snowball 词干提取的全文搜索
calc	单元格、工作表、公式、图表、条件格式、批注
draw	形状、页面、幻灯片、占位符、母版幻灯片、切换效果（Draw 和 Impress）
images / documents	图像和文档库提供程序（浏览并重复使用现有资源）
ai_images	AI 图像生成与编辑（Stable Diffusion、OpenAI、AI Horde）
ai	AI 文本提供程序，通过 Calc 的 =PROMPT() 函数调用
launcher	从 LibreOffice 启动 Claude Code、Gemini CLI 或 OpenCode
panel	侧边栏面板——MCP 操作日志、正在运行的作业
batch	通过变量串联执行多个工具
http	共享 HTTP 服务，可选 SSL
mcp	MCP JSON-RPC 协议处理程序
tunnel	隧道管理器（ngrok、Cloudflare、bore、Tailscale）

关闭不使用的功能

Nelson 提供了许多工具，但客户端不会看到全部工具，而且大多数筛选都会自动完成。以下按筛选力度从高到低排列：

调节方式	作用	位置
文档类型	工具列表会随当前文档而变化：Writer 约有 97 个工具，Calc 约有 50 个，总计 145 个。此过程自动完成，发生变化时会通知客户端	无需配置
未配置的功能会自动隐藏	Gallery 和 AI 图像工具会完全隐藏，直到你配置图库或图像提供商。启动器和隧道不会公开任何工具	无需配置
自定义端点	在专属 URL 上仅公开你选择的工具，例如在 /mcp/minimal 上公开 8 个工具。这是让小型模型严格遵循指令的最可靠方式	Options > Nelson MCP > MCP
预设	现成的端点工具列表：minimal、writer-edit、writer-read、calc、gallery	Options > Nelson MCP > MCP
功能开关	直接关闭 MCP 服务、HTTP 配置 API 或调试 API	各模块的 Options
提供商选择	选择要使用的隧道、启动器或 AI 提供商	各模块的 Options
启动时扫描	停止在启动时重新扫描图像和文档文件夹索引	Gallery 模块的 Options

因此，Calc 用户无需进行任何设置，工具数量就已降至 48 个；自定义端点则可以进一步缩减到你想要的数量。

Nelson 有意不提供阻止模块加载的开关。这会成为第七个重复的控制项，实际作用却很有限：31 个模块的完整启动耗时约为 370 ms，而且可选功能系列已经不会显示在工具列表中。测量数据请参阅 #29。

开发

./install.sh              # Set up dev environment
make deploy               # Build + install + restart LO + show log
make test                 # Run tests
make release              # Tag, build and publish a release (see scripts/release.sh)

完整的开发者指南请参阅 DEVEL.md，模块框架参考请参阅 docs/modules.md。

使用 AI Agent 进行开发

本项目使用 AI 编码 Agent 开发，并借助 wbox-mcp 让这一过程切实可行。

Nelson 运行在 LibreOffice 内部，因此 Agent 必须实际运行 LibreOffice，才能验证修改；而无头进程无法显示徽标是否确实出现在页面页眉中。wbox-mcp 是一个 MCP 服务，它会在嵌套的 Wayland 合成器中为 Agent 提供一个沙盒化的 LibreOffice：Agent 可以终止、部署并重新启动扩展，操作 UI，读取 Nelson 日志，还可以对结果进行截图。

这样就形成了完整的验证闭环。Agent 编辑代码、重新部署、通过 MCP 调用工具，并查看渲染后的文档来确认修改生效，而不是仅仅假定它已生效。

文档

• QUICKSTART.md — Agent 指南：发现、工作流、工具模式
• AGENTS.md — 开发者速查表：项目结构、构建流程、关键规则
• docs/howto/ — 用户指南：Tailscale + ChatGPT、Forge、Ollama 索引、图像图库
• docs/roadmap.md — 后续计划
• CHANGELOG.md — 版本历史

致谢

Nelson MCP 是通过合并并改造另外两个项目而来：

• LocalWriter — 一个 LibreOffice 扩展，内嵌了一个可使用 AI 提供商（兼容 OpenAI 的 API、Ollama、AI Horde）的聊天机器人侧边栏。它最初由 Umut Çelik 创建，名为 LibreCalc AI Assistant，之后由 @balisujohn 分叉并扩展，再由 @KeithCu（Keith Curtis）大幅完善；他添加了 AI Horde 支持、多提供商管理、聊天机器人侧边栏，以及 Calc =PROMPT() 集成。模块框架、工具系统和模块级配置架构由 @quazardous 开发。

• mcp-libre — 一个独立的 LibreOffice MCP 服务，通过 MCP 向外部 AI 客户端提供 Writer 工具。它表明，MCP 方案（外部 AI + 文档工具）比内嵌聊天机器人更灵活。Nelson MCP 采用以 MCP 为先的架构：移除了聊天机器人和 AI 提供商模块，扩展完全专注于为外部客户端提供工具服务。

许可证

MPL 2.0 — 参见 extension/registration/license.txt。