Format Converter MCP

Universal format conversion MCP Server

A Model Context Protocol (MCP) server covering full-format conversion across audio, video, images, Office, data, ebooks, PDF, subtitles, and more. It can be called by any MCP client such as TimeVerse Studio, Claude Desktop, Cursor, VS Code, etc.

English

✨ Features

Related MCP server: ChangeThisFile MCP Server

📦 Supported Formats

* marks restricted formats (PAGES / WPS / NUMBERS / KEY), requiring macOS native apps or iCloud export.

Total of approximately 71 formats after deduplication, covering 95%+ of common industry conversion needs.

⚠️ Known Limitations

• Restricted formats: PAGES / WPS / NUMBERS / KEY require macOS native apps or iCloud export; they usually cannot be converted directly on other platforms.

• HEIC/HEIF decoding: Depends on ImageMagick's libheif support; Apple's high-efficiency images cannot be decoded when it is missing.

• Engine fallback: If LaTeX is not installed, Markdown→PDF degrades to weasyprint; if Calibre is not installed, MOBI/AZW3 ebooks are unavailable; if ImageMagick is not installed, image conversion falls back to Python Pillow (with more limited capabilities).

• Protocol Buffers: Converting to PB requires an additional .proto definition file.

• Parquet / Protobuf: The corresponding Python dependencies (pyarrow, protobuf) are optional and must be installed manually.

🧰 Tool List

Core Conversion Tools (10)

Auxiliary Tools (4)

All conversion tools uniformly follow the input_path + output_format + options parameter paradigm.

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│              MCP Client (LLM)                        │
│        Claude / Cursor / VS Code / ...               │
└──────────────────────┬──────────────────────────────┘
                       │ JSON-RPC (stdio)
┌──────────────────────┴──────────────────────────────┐
│           MCP Protocol Layer                         │
│      tool list · tool call · notifications           │
├──────────────────────────────────────────────────────┤
│           Tool Router Layer                          │
│    请求解析 → 格式识别 → 路由分发 → 结果封装           │
├───────────┬───────────┬──────────┬───────────────────┤
│  Format   │ Conversion│  File    │  Dependency       │
│  Registry │  Planner  │ Manager  │  Checker          │
├───────────┴───────────┴──────────┴───────────────────┤
│           Conversion Engine Layer                    │
│  FFmpeg · ImageMagick · LibreOffice · Pandoc         │
│  Python · PDF                                         │
└──────────────────────────────────────────────────────┘

Smart path planning examples:

⚙️ Tech Stack

• Primary language: TypeScript (Node.js ≥ 18)

• Protocol: @modelcontextprotocol/sdk

• Conversion engines: FFmpeg / ImageMagick / LibreOffice / Pandoc / Python (venv isolated) / PyMuPDF

System Dependencies

LaTeX (optional, high-quality Markdown→PDF) and Calibre (optional, MOBI/AZW3) can be omitted; the system will automatically degrade.

Python Dependencies

pip install -r python/requirements.txt

Core dependencies: openpyxl, pandas, PyYAML, tomlkit, xmltodict, PyMuPDF, pypdf, pdf2docx, pysubs2, Pillow (pyarrow, protobuf are optional).

🚀 Installation

First install the system dependencies (FFmpeg / ImageMagick / LibreOffice / Pandoc):

• Windows: npm run prepare-deps (one-click download of portable versions)

• macOS: brew install ffmpeg imagemagick pandoc && brew install --cask libreoffice

• Linux: apt install ffmpeg imagemagick libreoffice pandoc

Then build and install the Python dependencies:

# 1. 安装 Node 依赖
npm install

# 2. 构建（生成 dist/）
npm run build

# 3. 安装 Python 依赖（建议使用虚拟环境）
python3 -m venv .venv        # macOS/Linux；Windows 使用 python
source .venv/bin/activate    # macOS/Linux；Windows 使用 .venv\Scripts\activate
pip install -r python/requirements.txt

🔌 MCP Configuration

Add the following server to the mcpServers configuration of your MCP client.

TimeVerse Studio (Recommended · npm hosted)

TimeVerse Studio uses the standard mcpServers JSON integration. After publishing to npm, run it directly via npx with one command — no local build required:

{
  "mcpServers": {
    "timeverse-omni-converter-mcp": {
      "command": "npx",
      "args": ["-y", "timeverse-omni-converter-mcp"],
      "env": {
        "FC_PYTHON_PATH": "python",
        "FC_TEMP_DIR": "C:/temp/format-converter",
        "FC_MAX_FILE_SIZE": "524288000",
        "FC_TIMEOUT": "300000"
      }
    }
  }
}

Claude Desktop / Cursor (local build)

After building locally, run directly via node:

{
  "mcpServers": {
    "timeverse-omni-converter-mcp": {
      "command": "node",
      "args": ["C:/path/to/timeverse-omni-converter-mcp/dist/index.js"],
      "env": {
        "FC_PYTHON_PATH": "python",
        "FC_TEMP_DIR": "C:/temp/format-converter",
        "FC_MAX_FILE_SIZE": "524288000",
        "FC_TIMEOUT": "300000"
      }
    }
  }
}

macOS: change args to /Users/<you>/timeverse-omni-converter-mcp/dist/index.js, and change FC_PYTHON_PATH to python3 (or remove the entry to let it auto-detect .venv/python3).

🔧 Environment Variables

💬 Usage Examples

Give natural language instructions to the LLM in your MCP client, for example:

• "Convert a.mov to a.mp4, resolution 1920x1080" → convert_media

• "Convert photo.heic to photo.png" → convert_image

• "Convert report.docx to report.pdf" → convert_document

• "Convert data.json to data.csv" → convert_data

• "Export every page of slides.pptx as PNG" → convert_presentation

• "Convert book.epub to book.mobi" → convert_ebook

• "Merge a.pdf and b.pdf" → convert_pdf (operation: "merge")

• "Convert subs.ass to subs.srt" → convert_subtitle

Tool call example:

{
  "name": "convert_media",
  "arguments": {
    "input_path": "C:/media/input.mov",
    "output_format": "mp4",
    "options": {
      "video_codec": "libx264",
      "video_resolution": "1920x1080",
      "crf": 23
    }
  }
}

Returned result:

{
  "success": true,
  "outputPath": "C:/media/input.mp4",
  "outputSize": 10485760,
  "duration": 3215,
  "warnings": []
}

❓ FAQ

Q: What should I do if conversion reports missing dependencies or fails? A: Call the check_dependencies tool to view the availability status and versions of each engine (FFmpeg / ImageMagick / LibreOffice / Pandoc / Python), install the missing dependencies, and retry.

Q: Python-related conversions (data / PDF / spreadsheet / subtitle) report errors? A: Make sure the dependencies have been installed via pip install -r python/requirements.txt, and point FC_PYTHON_PATH to the correct Python interpreter (or an activated virtual environment).

Q: What happens if the target file already exists? A: By default it is automatically renamed to filename_1.extension; for batch conversion, the on_conflict parameter can control overwrite / skip / rename.

Q: Why can't certain formats (such as PAGES / NUMBERS) be converted? A: These are Apple proprietary formats that require macOS native apps or iCloud export. They are restricted formats — see "Known Limitations" for details.

Q: What should I do if large file conversion times out? A: Increase FC_TIMEOUT (default 300000ms), and note the FC_MAX_FILE_SIZE (default 500MB) limit.

🛡️ Security

The server processes untrusted file content and has multiple built-in resource and security protections:

• Input file size, extracted volume, compression ratio, and image pixel limits (anti zip bomb / decompression bomb)

• Per-conversion timeout and concurrency limits

• Parsers disable XXE (external entity injection), PDF embedded scripts, and external resource loading

• External processes are uniformly invoked with argument arrays (execFile) to avoid command injection

📄 License

MIT