What is Magicconvert Mcp Server

magicconvert_mcp_server is a Model Context Protocol (MCP) server that utilizes the MagicConvert library to provide extensive file, URL, and text conversion capabilities, delivering outputs in clean, structured Markdown format.

Use cases

Use cases include converting academic papers from PDF to Markdown for easier editing, extracting content from web pages into Markdown for documentation, and transforming image files into text using OCR for data entry tasks.

How to use

To use magicconvert_mcp_server, first install the core library with ‘pip install magicconvert’ and then the MCP server package with ‘pip install magicconvert-mcp-server’. Configure the server in your MCP configuration file and run it using ‘uvx magicconvert-mcp-server’.

Key features

Key features include document conversion for formats like Word, PDF, PowerPoint, Excel, and CSV; image OCR for various image formats; web content to Markdown conversion; flexible input options including local files, Base64 uploads, and direct URLs; and clean, structured Markdown output.

Where to use

magicconvert_mcp_server can be used in various fields such as document management, web content extraction, educational tools, and any application requiring conversion of files or web content into Markdown format.

MagicConvert MCP Server

A Model Context Protocol (MCP) server that provides robust and extensible file, URL, and text conversion capabilities using the MagicConvert library. Outputs are delivered in clean, structured Markdown format.

---

🌟 Features

• ✅ Document Conversion:

  • Word .docx
  • PDF .pdf
  • PowerPoint .pptx
  • Excel .xlsx
  • CSV .csv

• 🖼️ Image OCR:

  • JPEG .jpg, .jpeg
  • PNG .png
  • TIFF .tiff
  • BMP .bmp

• 🌐 Web Content to Markdown:

  • URLs (http://, https://)
  • HTML Files .html, .htm

• ✍️ Text Conversion:

  • Plain text
  • HTML
  • CSV

• 🧩 Flexible Input Options:

  • Local file paths
  • Base64 encoded uploads
  • Direct URLs
  • Raw text input

• 🧼 Clean Output:

  • Well-structured, readable Markdown output

• 🔁 Temporary File Handling:

  • Secure and automatic temp file creation and cleanup

---

🚀 Installation

Prerequisites

Install the core library:

pip install magicconvert

Install the MCP server package:

pip install magicconvert-mcp-server

---

Run with uvx (Recommended)

Add the server in your MCP configuration (mcp.yaml or .mcp/config.json):

{
  "mcpServers": {
    "magicconvert": {
      "command": "uvx magicconvert-mcp-server"
    }
  }
}

Then run the server:

uvx magicconvert-mcp-server

---

🛠️ Supported Tools

The server exposes the following tools via MCP:

1. convert_file_to_markdown

Description: Converts a file from the local file system to Markdown.

{
  "file_path": "/path/to/your/file.pdf"
}

---

2. convert_base64_file_to_markdown

Description: Accepts a base64 encoded file (from uploads) and converts it.

{
  "base64_data": "base64string==",
  "filename": "document.pdf"
}

---

3. convert_url_to_markdown

Description: Downloads a webpage or document from a URL and converts it.

{
  "url": "https://example.com/article"
}

---

4. convert_text_to_markdown

Description: Converts raw text content into Markdown. Supports plain text, HTML, and CSV.

{
  "text_content": "<p>Hello</p>",
  "format_type": "html"
}

Accepted format_type values:

• plain (default)
• html
• csv

---

5. get_supported_formats

Description: Returns a Markdown-formatted list of supported input types and features.

No parameters required.

---

📦 Example Usage

from mcp.client import Client

client = Client()

response = client.call_tool("magicconvert", "convert_file_to_markdown", {
    "file_path": "example.pdf"
})

print(response[0].text)

---

🔒 Temporary File Management

All temporary files created (e.g., for base64 or text inputs) are:

• Stored in a platform-safe temporary directory (e.g., /tmp, %TEMP%)
• Cleaned up automatically after conversion
• Validated for path safety

---

⚙️ Logging

The server logs messages to the mcp_magicconvert_server logger.

To enable debug logging, set the environment variable:

export LOGLEVEL=DEBUG

---

🧪 Development & Testing

Clone the repository and run:

python -m magicconvert_mcp_server

To run with stdio transport (MCP):

uvx magicconvert-mcp-server

To test via CLI, MCP-compatible clients like mcp[cli] are recommended.

---

📚 Advanced: MCP Integration

This library is designed for use in MCP-compatible environments, such as:

• OpenAI’s API calling tools
• LangChain or LlamaIndex with MCP extensions
• Custom MCP client implementations

---

🧠 Internals Overview

The server defines:

• A MagicConvertProcessor that wraps around the core MagicConvert logic
• Full support for async base64 decoding using aiofiles
• Smart MIME inference via filenames and extensions
• A modular Server class using the mcp framework with defined tool interfaces

---

📄 License

MIT License. See LICENSE for details.

---

🔗 Links

• PyPI: magicconvert-mcp-server
• Core Library: MagicConvert
• MCP Protocol: mcp-spec