LibreOffice MCP 도구

npm version

AI 에이전트(Claude, Copilot, Gemini, Cursor 등)가 LibreOffice를 통해 Office 문서를 읽고, 쓰고, 편집할 수 있는 능력을 제공하는 Model Context Protocol (MCP) 서버입니다. LLM 컨텍스트 사용을 최소화하는 토큰 효율적인 설계가 적용되었습니다.

chrome-devtools-mcp의 아키텍처에서 영감을 받았습니다.

✨ 주요 기능

22개의 MCP 도구: 읽기, 쓰기, 스프레드시트, 프레젠테이션 기능 포함
토큰 효율적 설계: 개요 우선 탐색, 범위 기반 액세스, 페이지네이션
광범위한 형식 지원: 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 read / JSZip OOXML write)
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 등)

읽기 (토큰 효율적)

도구	설명
`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 + 마크다운 테이블 형식의 셀 범위
`spreadsheet_set_cell`	셀 값 또는 수식 설정
`spreadsheet_set_range`	2D 값 범위 설정
`spreadsheet_add_sheet`	새 시트 추가
`spreadsheet_get_formulas`	범위 내 수식 표현식 가져오기

프레젠테이션 (Impress)

도구	설명
`presentation_list_slides`	인덱스를 포함한 슬라이드 제목
`presentation_get_slide`	전체 슬라이드 콘텐츠 (제목, 본문, 노트)
`presentation_get_notes`	발표자 노트
`presentation_add_slide`	새 슬라이드 추가 (LibreOffice 필요)
`presentation_update_slide`	슬라이드 콘텐츠 업데이트

💡 토큰 절약 워크플로우

최대 토큰 효율성을 위해 다음 패턴을 따르세요:

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