PeterHeick/odt-mcp-server

ODT MCP Server

A Model Context Protocol (MCP) server for handling OpenDocument Text (.odt) files. This server enables AI assistants to read, analyze, and extract data from ODT documents.

Features

• Read ODT text: Extract clean text from ODT documents
• Get metadata: Retrieve document information like author, title, date, etc.
• List archive contents: See all files contained in the ODT archive
• Extract raw XML: Access the underlying XML files (content.xml, styles.xml, meta.xml)

Prerequisites

• Node.js v18.0.0 or later
• npm (included with Node.js)

Installation

npm install
npm run build
npm link

Quick Start

🚀 Try the Interactive Demo

# Run the full-featured demo
cd examples
node demo.js

# Or test with your own ODT file  
node demo.js path/to/your/file.odt

As MCP Server

The server is designed to be used as an MCP server with AI assistants like Claude or other MCP-compatible clients.

# Run the server directly
./build/index.js

# Or after npm link, run globally
odt-mcp-server

Available Tools

1. read_odt

Reads and extracts clean text from an ODT file.

Input:

• file_path (string): Path to the ODT file

Output: Clean text from the document

2. get_odt_metadata

Retrieves metadata from the ODT file's meta.xml.

Input:

• file_path (string): Path to the ODT file

Output: JSON object with document metadata

3. list_odt_files

Lists all files in the ODT archive.

Input:

• file_path (string): Path to the ODT file

Output: List of filenames in the archive

4. extract_odt_xml

Extracts raw XML content from a specific file in the ODT archive.

Input:

• file_path (string): Path to the ODT file
• xml_file (string): Name of the XML file (e.g., 'content.xml', 'styles.xml', 'meta.xml')

Output: Raw XML content

MCP Configuration

To use this server with an MCP client, add the following to your configuration:

{
  "mcpServers": {
    "odt": {
      "command": "odt-mcp-server"
    }
  }
}

Note: After running npm link, the odt-mcp-server command will be globally available.

Development

# Build the project
npm run build

# Build in watch mode
npm run watch

Technical Details

• Runtime: Node.js with ES modules
• Dependencies:
  • @modelcontextprotocol/sdk: MCP SDK
  • adm-zip: ZIP archive handling
  • xml2js: XML parsing
• Type definitions: Full TypeScript support

About the ODT Format

OpenDocument Text (.odt) files are ZIP archives that contain:

• content.xml: The document's main content
• meta.xml: Metadata (author, title, etc.)
• styles.xml: Formatting and styles
• META-INF/manifest.xml: Archive manifest
• Other resources (images, fonts, etc.)

This server provides structured access to all these components through the MCP protocol.

Contributing

Contributions are welcome! Here's how you can help:

1. Report Issues: Found a bug or have a feature request? Open an issue
2. Submit Pull Requests: Fork the repository, make your changes, and submit a pull request
3. Improve Documentation: Help make the documentation clearer and more comprehensive
4. Test with ODT Files: Test with various ODT files and report compatibility issues

Development Setup

git clone https://github.com/PeterHeick/odt-mcp-server.git
cd odt-mcp-server
npm install
npm run build
npm run watch  # For development with auto-rebuild

Please ensure your code follows the existing style and includes appropriate tests.

License

MIT - Feel free to use this project for any purpose, commercial or non-commercial. See the full license text for details.