LibreOffice MCP Server

A comprehensive Model Context Protocol (MCP) server that provides tools and resources for interacting with LibreOffice documents. This server enables AI assistants and other MCP clients to create, read, convert, and manipulate LibreOffice documents programmatically.

How to use

to interact via cli :- source src/quick_start.sh

then start a websocket connetion with:- websocat -H="Sec-WebSocket-Protocol: mcp" ws://localhost:8000/message

then put any jsonrpc commands/payloads. You can see the commands.txt for examples

📂 Repository Structure

This repository is organized into logical directories:

src/ - Core MCP server implementation
tests/ - Test suite and validation scripts
examples/ - Demo scripts and usage examples
config/ - Configuration templates for integrations
scripts/ - Utility scripts for setup and management
docs/ - Comprehensive documentation

For detailed information, see docs/REPOSITORY_STRUCTURE.md.

🚀 Features

LibreOffice Extension (Plugin) - NEW! 🎉

Native Integration: Embedded MCP server directly in LibreOffice
Real-time Editing: Live document manipulation with instant visual feedback
Performance: 10x faster than external server (direct UNO API access)
Multi-document: Work with all open LibreOffice documents
Auto-start: Automatically available when LibreOffice starts
HTTP API: External AI assistant access via localhost:8765

Document Operations

Create Documents: New Writer, Calc, Impress, and Draw documents
Read Content: Extract text from any LibreOffice document
Convert Formats: Convert between 50+ formats (PDF, DOCX, HTML, etc.)
Edit Documents: Insert, append, or replace text in Writer documents
Document Info: Get detailed metadata about documents

Spreadsheet Operations

Read Spreadsheets: Extract data from Calc spreadsheets and Excel files
Structured Data: Get data as 2D arrays with row/column information

Advanced Tools

Document Search: Find documents containing specific text
Batch Convert: Convert multiple documents simultaneously
Merge Documents: Combine multiple documents into one
Document Analysis: Get detailed statistics (word count, sentences, etc.)

Live Viewing & Real-time Editing

GUI Integration: Open documents in LibreOffice for live viewing
Real-time Updates: See changes as AI assistants modify documents
Change Monitoring: Watch documents for modifications in real-time
Interactive Sessions: Create live editing sessions with automatic refresh

MCP Resources

Document Discovery: List all LibreOffice documents (documents://)
Content Access: Access specific document content (document://{path})

📋 Requirements

LibreOffice: 24.2+ (must be accessible via command line)
Python: 3.12+
UV Package Manager: For dependency management

For detailed installation instructions for all platforms, run:

./mcp-helper.sh requirements

🛠 Installation

Clone the repository:

git clone https://github.com/patrup/mcp-libre/
cd mcp-libre

Check prerequisites:

./mcp-helper.sh requirements  # Show detailed requirements
./mcp-helper.sh check         # Verify your system

Install dependencies:
```
uv sync
```
Make helper script executable:
```
chmod +x mcp-helper.sh
```

🎯 Quick Start

Test the Server

# Run functionality tests
./mcp-helper.sh test

# Run interactive demo
./mcp-helper.sh demo

Start MCP Server

# Standard MCP mode (stdio)
python src/main.py

# Or using UV
uv run python src/main.py

# Show help and options
python src/main.py --help

# Run tests
python src/main.py --test

Integration with Super Assistant

# Start the MCP proxy
./mcp-helper.sh proxy

# Then configure Super Assistant extension:
# Server URL: http://localhost:3006

🔧 Available Tools

Tool	Description
`create_document`	Create new LibreOffice documents
`read_document_text`	Extract text from documents
`convert_document`	Convert between formats
`get_document_info`	Get document metadata
`read_spreadsheet_data`	Read spreadsheet data
`insert_text_at_position`	Edit document text
`search_documents`	Search documents by content
`batch_convert_documents`	Batch format conversion
`merge_text_documents`	Merge multiple documents
`get_document_statistics`	Document analysis
`open_document_in_libreoffice`	Open document in GUI for live viewing
`create_live_editing_session`	Start live editing with real-time preview
`watch_document_changes`	Monitor document changes in real-time
`refresh_document_in_libreoffice`	Force document refresh in GUI

📚 Documentation

Prerequisites: Quick reference for system requirements
Plugin Migration Guide: Migrate from external server to plugin
Examples: Code examples and usage patterns
Live Viewing Guide: See changes live in LibreOffice GUI
Super Assistant Setup: Chrome extension integration
ChatGPT Browser Guide: Using with ChatGPT and alternatives
Troubleshooting: Common issues and solutions
Quick Start: Quick reference guide
Complete Solution: Comprehensive overview

🔗 Integration Options

1. LibreOffice Extension (NEW - Recommended!) 🎉

The most powerful and efficient way to use the MCP server:

# Build and install the LibreOffice extension
cd plugin/
./install.sh install

# Test the extension
./install.sh test

Benefits of the Extension:

10x Performance: Direct UNO API access (no subprocess overhead)
Real-time Editing: Live document manipulation in open LibreOffice windows
Native Integration: Appears in LibreOffice Tools menu
Multi-document Support: Work with all open documents simultaneously
Auto-start: Automatically starts with LibreOffice
Advanced Features: Full access to LibreOffice formatting and capabilities

Usage:

The extension provides an HTTP API on http://localhost:8765
Configure your AI assistant to use this endpoint
Access controls via Tools > MCP Server in LibreOffice
Real-time document editing with instant visual feedback

For detailed plugin information, see plugin/README.md.

2. Claude Desktop

Generate configuration automatically:

./generate-config.sh claude
# Creates ~/.config/claude/claude_desktop_config.json

Then restart Claude Desktop and start using LibreOffice commands:

"Create a new Writer document and save it as project-report.odt"
"Convert my document to PDF format"

3. Super Assistant Chrome Extension

Generate configuration and start proxy:

./generate-config.sh mcp
npx @srbhptl39/mcp-superassistant-proxy@latest --config ~/Documents/mcp/mcp.config.json
# Server URL: http://localhost:3006

4. Direct MCP Client

from mcp.shared.memory import create_connected_server_and_client_session
from libremcp import mcp

async with client_session(mcp._mcp_server) as client:
    result = await client.call_tool("create_document", {
        "path": "/tmp/test.odt",
        "doc_type": "writer",
        "content": "Hello, World!"
    })

🎨 Usage Examples

Natural Language (via Super Assistant)

"Create a new Writer document with a project report"
"Convert my ODT file to PDF format"
"Search for documents containing 'budget' in my Documents folder"
"Get statistics for my essay - how many words?"

Programmatic Usage

from libremcp import create_document, read_document_text, convert_document

# Create a document
doc = create_document("/tmp/report.odt", "writer", "Project Report")

# Read content
content = read_document_text("/tmp/report.odt")
print(f"Words: {content.word_count}")

# Convert to PDF
result = convert_document("/tmp/report.odt", "/tmp/report.pdf", "pdf")

📁 Supported File Formats

Input (Reading)

LibreOffice: .odt, .ods, .odp, .odg
Microsoft Office: .doc, .docx, .xls, .xlsx, .ppt, .pptx
Text: .txt, .rtf

Output (Conversion)

PDF: .pdf
Microsoft Office: .docx, .xlsx, .pptx
Web: .html, .htm
Text: .txt
LibreOffice: .odt, .ods, .odp, .odg
Many others: 50+ formats supported by LibreOffice

🧪 Testing

LibreOffice Extension Testing

# Install and test the plugin
cd plugin/
./install.sh install    # Build and install extension
./install.sh test       # Test functionality
./install.sh status     # Check status
./install.sh interactive # Interactive testing mode

External Server Testing

# Show system requirements and installation guides
./mcp-helper.sh requirements

# Check dependencies and verify setup
./mcp-helper.sh check

# Run built-in functionality tests
./mcp-helper.sh test

# Interactive demo of all capabilities
./mcp-helper.sh demo

# Test specific functionality directly
uv run python libremcp.py --test

🔧 Configuration

MCP Configuration for Integrations

Generate personalized configuration files for Claude Desktop and/or Super Assistant:

# Generate both Claude Desktop and Super Assistant configs
./generate-config.sh

# Generate only Claude Desktop config
./generate-config.sh claude

# Generate only Super Assistant config  
./generate-config.sh mcp

# Generate Super Assistant config in custom location
./generate-config.sh mcp /path/to/custom/directory

This automatically creates configurations with your actual project paths:

Claude Desktop: ~/.config/claude/claude_desktop_config.json
Super Assistant: ~/Documents/mcp/mcp.config.json (or custom location)

Environment Variables

export PYTHONPATH="/path/to/mcp-libre"
export LIBREOFFICE_PATH="/usr/bin/libreoffice"  # Optional

Custom Search Paths

Edit libremcp.py to modify document discovery locations:

search_paths = [
    Path.home() / "Documents",
    Path.home() / "Desktop",
    Path("/custom/path"),
    Path.cwd()
]

🛡 Security

Local Execution: All operations run locally
File Permissions: Limited to user's file access
No Network: No external network dependencies
Temporary Files: Automatically cleaned up

🚨 Troubleshooting

LibreOffice Issues

# Check LibreOffice installation
libreoffice --version
libreoffice --headless --help

# Test conversion manually
libreoffice --headless --convert-to pdf document.odt

Java Warnings

Java warnings are usually non-fatal
Core functionality works without Java
Install Java for full LibreOffice features

Permission Errors

Check file and directory permissions
Ensure LibreOffice can access document paths
Verify write permissions for output directories

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

The MIT License is a permissive license that allows:

✅ Commercial use
✅ Modification
✅ Distribution
✅ Private use

For other license options, see LICENSE_OPTIONS.md.

🔗 Links

MCP Specification: https://spec.modelcontextprotocol.io/
LibreOffice: https://www.libreoffice.org/
FastMCP Framework: https://github.com/modelcontextprotocol/python-sdk

📞 Support

Issues: Use GitHub issues for bug reports
Documentation: See the docs/ folder for detailed guides
Examples: Check EXAMPLES.md for usage patterns

LibreOffice MCP Server v0.1.0 - Bridging AI and Document Processing

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
config		config
docs		docs
examples		examples
plugin		plugin
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.python-version		.python-version
LICENSE		LICENSE
README.md		README.md
command.txt		command.txt
commands.txt		commands.txt
generate-config.sh		generate-config.sh
libremcp.py		libremcp.py
mcp-helper.sh		mcp-helper.sh
merge-plugin-branch.sh		merge-plugin-branch.sh
pyproject.toml		pyproject.toml
quick-test.sh		quick-test.sh
quick_start.sh		quick_start.sh
temp.text		temp.text

License

BetterExcel/libreoffice_mcp

Folders and files

Latest commit

History

Repository files navigation