LibreOffice MCP 工具

npm version

一个 Model Context Protocol (MCP) 服务器，使 AI 智能体（Claude、Copilot、Gemini、Cursor 等）能够通过 LibreOffice 读取、写入和编辑 Office 文档 —— 采用节省 Token 的设计，最大限度地减少 LLM 上下文的使用。

灵感来源于 chrome-devtools-mcp 的架构。

✨ 特性

22 个 MCP 工具，涵盖读取、写入、电子表格和演示文稿
节省 Token 的设计：以大纲为先的导航、基于范围的访问、分页功能
广泛的格式支持：DOCX、DOC、XLSX、XLS、PPTX、PPT、ODT、ODS、ODP、RTF、CSV、TXT、PDF
旧版格式桥接：.doc、.xls、.ppt 在解析前通过 LibreOffice 自动转换
基础读取无需 LibreOffice：原生解析器直接处理 DOCX、XLSX、PPTX
LibreOffice 仅在以下情况需要：旧版格式、PDF 导出、格式转换

📋 支持的格式

格式	扩展名	读取	写入	方法
Word 2007+	`.docx`, `.dotx`	✅	✅	原生 (mammoth 读取 / JSZip OOXML 写入)
Word 97-2003	`.doc`, `.dot`	✅	✅	LibreOffice 桥接
Excel 2007+	`.xlsx`, `.xlsm`	✅	✅	原生 (ExcelJS)
Excel 97-2003	`.xls`	✅	✅	LibreOffice 桥接
PowerPoint 2007+	`.pptx`	✅	✅	原生 (JSZip OOXML)
PowerPoint 97-2003	`.ppt`	✅	✅	LibreOffice 桥接
OpenDocument Text	`.odt`	✅	✅	LibreOffice 桥接
OpenDocument Spreadsheet	`.ods`	✅	✅	LibreOffice 桥接
OpenDocument Presentation	`.odp`	✅	✅	LibreOffice 桥接
Rich Text Format	`.rtf`	✅	✅	LibreOffice 桥接
CSV	`.csv`	✅	✅	原生
PDF	`.pdf`	✅ (文本)	❌	LibreOffice CLI
纯文本	`.txt`	✅	✅	原生

🚀 快速开始

前置要求

Node.js 20+
LibreOffice (基础 DOCX/XLSX/PPTX 读取可选；.doc/.xls/.ppt 及格式转换必需)
- Windows: 下载 LibreOffice
- macOS: brew install --cask libreoffice
- Linux: sudo apt install libreoffice 或 sudo dnf install libreoffice

安装

使用 npx (推荐 — 无需安装):

{
  "mcpServers": {
    "libreoffice": {
      "command": "npx",
      "args": ["-y", "@passerbyflutter/libreoffice-mcp-tools"]
    }
  }
}

全局安装:

npm install -g @passerbyflutter/libreoffice-mcp-tools

从源码安装:

git clone https://github.com/passerbyflutter/libreoffice-mcp-tools
cd libreoffice-mcp-tools
npm install
npm run build

配置 MCP 客户端

添加到您的 MCP 客户端配置中（例如 Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "libreoffice": {
      "command": "npx",
      "args": ["-y", "@passerbyflutter/libreoffice-mcp-tools"],
      "env": {
        "SOFFICE_PATH": "/path/to/soffice"
      }
    }
  }
}

或者在项目根目录使用 .mcp.json：

{
  "mcpServers": {
    "libreoffice": {
      "command": "npx",
      "args": ["-y", "@passerbyflutter/libreoffice-mcp-tools"]
    }
  }
}

CLI 选项

node build/bin/libreoffice-mcp.js [options]

  --libreoffice-path <path>   Path to soffice executable
                              (default: auto-detected or SOFFICE_PATH env)

🛠 工具参考

文档管理

工具	描述
`document_open`	打开文件 → 返回 `docId` 句柄。自动桥接旧版格式。
`document_close`	释放文档句柄和临时文件
`document_list`	列出所有打开的文档
`document_create`	创建新的空文档 (Writer/Calc/Impress)
`document_save`	保存到当前或新路径
`document_export`	通过 LibreOffice 导出 (PDF, HTML, CSV 等)
`document_convert`	转换文件格式 (DOC→DOCX, XLSX→CSV 等)

读取 (节省 Token)

工具	描述
`document_get_metadata`	标题、作者、字数/页数、日期
`document_get_outline`	标题 (Writer) / 工作表名称 (Calc) / 幻灯片标题 (Impress)
`document_read_text`	以 Markdown 格式分页读取文档文本
`document_read_range`	指定段落或幻灯片范围
`document_search`	查找带有周围上下文的文本

写入 (Writer)

工具	描述
`document_insert_text`	在开头/结尾/标题后插入
`document_replace_text`	查找并替换 (首次或所有匹配项)
`document_insert_paragraph`	在指定索引处插入段落
`document_apply_style`	应用标题/段落样式

电子表格 (Calc)

工具	描述
`spreadsheet_list_sheets`	带有行/列计数的工作表名称
`spreadsheet_get_range`	以 JSON + Markdown 表格形式获取单元格范围
`spreadsheet_set_cell`	设置单元格值或公式
`spreadsheet_set_range`	设置二维值范围
`spreadsheet_add_sheet`	添加新工作表
`spreadsheet_get_formulas`	获取范围内的公式表达式

演示文稿 (Impress)

工具	描述
`presentation_list_slides`	带有索引的幻灯片标题
`presentation_get_slide`	完整的幻灯片内容 (标题、正文、备注)
`presentation_get_notes`	演讲者备注
`presentation_add_slide`	添加新幻灯片 (需要 LibreOffice)
`presentation_update_slide`	更新幻灯片内容

💡 节省 Token 的工作流

为了实现最大的 Token 效率，请遵循此模式：

1. document_open(filePath) → get docId
2. document_get_metadata(docId) → understand size/type
3. document_get_outline(docId) → see structure
4. document_read_range(docId, startIndex=N, endIndex=M) → read specific section

不要一次性转储整个文档，而是导航到您真正需要的部分。

电子表格工作流：

1. document_open(path) → docId
2. spreadsheet_list_sheets(docId) → see all sheets
3. spreadsheet_get_range(docId, sheetName="Sales", range="A1:D20") → targeted data

🏗 架构

src/
├── index.ts                # createMcpServer() — MCP server factory
├── LibreOfficeAdapter.ts   # soffice subprocess manager
├── DocumentContext.ts      # Open document registry
├── DocumentSession.ts      # Per-document state + format bridge
├── McpResponse.ts          # Response builder (text/JSON/markdown)
├── Mutex.ts                # Serializes LibreOffice subprocess calls
├── parsers/
│   ├── DocxParser.ts           # DOCX read → {paragraphs, outline, metadata} (mammoth)
│   ├── DocxOoxmlEditor.ts      # DOCX write → direct JSZip OOXML manipulation (format-preserving)
│   ├── XlsxParser.ts           # XLSX read/write via ExcelJS
│   ├── PptxParser.ts           # PPTX read → {slides[]} (JSZip XML)
│   └── PptxOoxmlEditor.ts      # PPTX write → add/update slides, create PPTX (JSZip OOXML)
├── formatters/
│   ├── MarkdownFormatter.ts
│   ├── JsonFormatter.ts
│   └── TableFormatter.ts   # Spreadsheet → Markdown table
└── tools/
    ├── documents.ts         # open/close/list/create
    ├── reader.ts            # metadata/outline/read/search
    ├── writer.ts            # insert/replace/style
    ├── spreadsheet.ts       # get/set cells/ranges/sheets
    ├── presentation.ts      # slides/notes
    └── converter.ts         # save/export/convert

🧪 测试

# Create sample fixtures
node tests/create-fixtures.mjs

# Run smoke tests
npm test

📝 环境变量

变量	描述
`SOFFICE_PATH`	LibreOffice `soffice` 可执行文件的路径
`DEBUG`	设置为 `lo-mcp:*` 以获取详细日志

📄 许可证

MIT

LibreOffice MCP Tools