jrodeiro5/media-tools

An MCP server that lets your AI client work with PDFs, images, audio, video and Office files. 104 tools, one command to start.

Quick start · Tools · CLI · Development

---

Ask your assistant to “merge these three PDFs, then compress the result” or “cut 10 seconds from this clip and make a GIF”. It calls the matching tools; the files never leave your machine.

Built on FastMCP. Works with any MCP client: Claude Desktop, OpenWebUI, Cursor and others.

Quick start

git clone https://github.com/jrodeiro5/media-tools && cd media-tools
uv sync
uv run media-tools-server        # http://localhost:8020/mcp

Point your client at it. For a client that reads an mcpServers block:

{
  "mcpServers": {
    "media-tools": { "url": "http://localhost:8020/mcp" }
  }
}

Set PORT to change the port. To expose only one family of tools (and keep the client’s context small), run a scoped server: media-tools-server-pdf, -image, -audio, -video, -office, -ai or -tts. Or set MEDIA_TOOLS_SEARCH=1 on the full server to list just search_tools + call_tool (~330 tokens instead of ~13.7k) and let the agent find tools by query.

Tools

pdf_to_docx uses LibreOffice by default (text ends up in text boxes). For real layout reconstruction install uv sync --extra docx, which adds pdf2docx and its AGPL-3.0 PyMuPDF dependency.

pii_scan and pii_redact need the optional extra (uv sync --extra pii, adds Presidio). They match by pattern and checksum, so names and addresses are not detected, and pii_scan returns masked previews, never the raw values.

pdf_redact renders the matched pages to images and paints over the matches, so the text is gone from the file, not just hidden. Those pages lose their selectable text.

CLI

The same toolkits run without a server:

media-tools pdf merge a.pdf b.pdf --output merged.pdf
media-tools pdf compress merged.pdf --output small.pdf
media-tools --help

The CLI covers most server tools, some under shorter names (pdf reorder, video info). Not in the CLI: the AI tools, text_to_speech, pdf_redact, pdf_info, pdf_to_docx, pdf_extract_structured / _screenshots, image_remove_background, image_to_video, audio_to_video, video_extract_audio and video_extract_frames.

Requirements

• Python 3.11 or newer and uv
• ffmpeg for audio and video, LibreOffice (soffice) for Office conversion, tesseract for OCR. On macOS: brew install ffmpeg tesseract && brew install --cask libreoffice
• Runtime extras for single tools: Ghostscript (gs, brew install ghostscript) for pdf_to_a, an ffmpeg build with libass for video_subtitle_burn, onnxruntime (pip install onnxruntime) for image_remove_background.
• Optional: OfficeCLI for office_inspect/office_edit (brew install officecli); the Firecrawl CLI plus FIRECRAWL_API_KEY for url_to_markdown (sends the URL to Firecrawl, unlike every other tool)
• Optional: a LiteLLM proxy for the AI tools, text to speech, and transcription

Development

uv sync --group dev
uvx pre-commit run --all-files   # ruff, mypy, bandit, semgrep, gitleaks

CI runs the same hooks on Python 3.11 and 3.13, plus CodeQL, gitleaks and zizmor. Found a vulnerability? Use the repository’s private vulnerability reporting rather than a public issue.

Roadmap: see ROADMAP.md (user-facing) and BACKLOG.md (technical gaps).

License

MIT. The logo wordmark is outlined from JetBrains Mono (SIL OFL 1.1).