Flexberry Markitdown

GitHub License: MIT PyPI version

MCP сервер для конвертации файлов в Markdown с использованием библиотеки MarkItDown от Microsoft.

Особенности

• 🔄 Конвертация файлов различных форматов в Markdown
• 📁 Большие файлы — результат сохраняется на диск, не загружается в контекст LLM
• 🌍 Поддержка кириллицы в документах и именах файлов
• 💻 Кроссплатформенность — Windows и Linux
• 🔧 Интеграция с RooCode через Model Context Protocol

Поддерживаемые форматы

Категория	Форматы
Документы	PDF, DOCX, DOC, PPTX, PPT, XLSX, XLS
Веб	HTML, HTM, XML, URL
Данные	CSV, JSON
Текст	MD, RST, TXT
Изображения (OCR)	PNG, JPG, JPEG, GIF, BMP, TIFF, WEBP
Аудио (транскрипция)	MP3, WAV, M4A, OGG, FLAC
Архивы	ZIP
Электронные книги	EPUB

⚠️ Для OCR изображений требуется установка Tesseract. Для транскрипции аудио требуется поддержка в системе.

Установка

Вариант 1: Установка из PyPI (рекомендуется)

# Установка через pip
pip install flexberry-markitdown-mcp

# Установка с зависимостями для разработки
pip install flexberry-markitdown-mcp[dev]

Вариант 2: Установка из исходного кода

# Клонируйте репозиторий
git clone https://github.com/Flexberry/flexberry-markitdown-mcp.git
cd flexberry-markitdown-mcp

# Создайте виртуальное окружение (опционально, но рекомендуется)
python -m venv .venv

# Активируйте виртуальное окружение
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# Установите зависимости
pip install -e .

Вариант 3: Использование установочного скрипта

Linux/macOS:

chmod +x install.sh
./install.sh

Windows:

install.bat

Настройка RooCode

Конфигурация для Windows

Добавьте в настройки RooCode (файл mcp_settings.json или через интерфейс):

{
  "mcpServers": {
    "flexberry-markitdown": {
      "command": "python",
      "args": ["-m", "flexberry_markitdown_mcp.server"]
    }
  }
}

Или с виртуальным окружением:

{
  "mcpServers": {
    "flexberry-markitdown": {
      "command": "C:\\path\\to\\flexberry-markitdown-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "flexberry_markitdown_mcp.server"],
      "cwd": "C:\\path\\to\\flexberry-markitdown-mcp"
    }
  }
}

Конфигурация для Linux

{
  "mcpServers": {
    "flexberry-markitdown": {
      "command": "python3",
      "args": ["-m", "flexberry_markitdown_mcp.server"]
    }
  }
}

Или с виртуальным окружением:

{
  "mcpServers": {
    "flexberry-markitdown": {
      "command": "/home/user/flexberry-markitdown-mcp/.venv/bin/python",
      "args": ["-m", "flexberry_markitdown_mcp.server"],
      "cwd": "/home/user/flexberry-markitdown-mcp"
    }
  }
}

Универсальная конфигурация (через uv)

Если используется uv:

{
  "mcpServers": {
    "flexberry-markitdown": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/flexberry-markitdown-mcp",
        "run",
        "flexberry-markitdown-mcp"
      ]
    }
  }
}

Доступные инструменты

convert_to_markdown

Конвертирует файл в Markdown и сохраняет результат рядом с исходным файлом.

Параметры:

• file_path (обязательный) — путь к файлу для конвертации
• output_path (опциональный) — пользовательский путь для сохранения результата
• overwrite (опциональный, по умолчанию false) — перезаписать существующий файл

Пример использования в RooCode:

Convert file /home/user/documents/report.pdf to Markdown

get_supported_formats

Возвращает список поддерживаемых форматов файлов.

check_file_exists

Проверяет существование файла и возвращает информацию о нем.

Примеры использования

Конвертация PDF с кириллицей

Convert file C:\Documents\Report 2024.pdf to Markdown

Результат будет сохранен в C:\Documents\Report 2024.md

Конвертация с перезаписью

Convert file /home/user/report.docx with overwrite existing

Конвертация в указанное место

Convert presentation.pptx and save result to /tmp/output.md

Обработка больших файлов

Сервер разработан для работы с файлами любого размера:

1. Файл конвертируется через MarkItDown
2. Результат сохраняется на диск рядом с исходным файлом
3. В контекст LLM возвращается только информация о пути и размере

Это позволяет работать с файлами, которые в 100 раз превышают лимит контекста LLM.

Журналирование

Журналы сервера сохраняются в:

• Linux: ~/.flexberry-markitdown-mcp/server.log
• Windows: C:\Users\<user>\.flexberry-markitdown-mcp\server.log

Устранение неполадок

Ошибка: "MarkItDown not installed"

pip install flexberry-markitdown-mcp

Ошибка: "MCP module not found"

pip install flexberry-markitdown-mcp

Проблемы с кириллицей в Windows

Убедитесь, что в терминале используется кодировка UTF-8. Сервер автоматически устанавливает UTF-8 для stdin/stdout/stderr.

OCR не работает для изображений

Установите Tesseract:

• Windows: загрузите с https://github.com/UB-Mannheim/tesseract/wiki
• Linux: sudo apt install tesseract-ocr (Ubuntu/Debian)

Для русского языка установите языковой пакет:

• Windows: выберите русский язык во время установки
• Linux: sudo apt install tesseract-ocr-rus

Транскрипция аудио не работает

MarkItDown использует Azure Speech Services для транскрипции. Убедитесь, что переменные среды настроены.

Разработка

Запуск тестов

pip install -e ".[dev]"
pytest

Структура проекта

flexberry-markitdown-mcp/
├── src/
│   └── flexberry_markitdown_mcp/
│       ├── __init__.py
│       └── server.py
├── pyproject.toml
├── README.md
├── install.sh
├── install.bat
├── uninstall.sh
├── uninstall.bat
└── roocode-config-examples.json

Лицензия

MIT License

---

Разработано командой Flexberry.