Universal AI Converter

Convert documents, images, audio, and video into Markdown or structured JSON. The core is agent-agnostic: use it from a terminal, Python, an HTTP API, an MCP-compatible AI agent, Docker, or your own application.

One-command Codex installation

The installer creates an isolated environment, installs all conversion features, installs the Codex plugin, and enables automatic file routing.

Windows PowerShell:

irm https://raw.githubusercontent.com/KOLRNCH/Universal-AI-Converter/main/install.ps1 | iex

macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/KOLRNCH/Universal-AI-Converter/main/install.sh | sh

Requirements: Python 3.10+ and Codex. Restart Codex and open a new task after installation. Attach a file and ask a normal question; the plugin selects the converter automatically.

FFmpeg and Tesseract are system programs. The Python features are installed automatically, while the installer reports any missing system executable when that format is first used.

Related MCP server: gobbler-mcp

Why it is portable

• No dependency on Codex, ChatGPT, Claude, or a specific LLM.

• A stable Python API and command-line interface form the core.

• MCP is an optional adapter for compatible agents.

• HTTP is an optional adapter for everything else.

• Heavy document, OCR, and speech dependencies are installed only when needed.

Install

Python 3.10 or newer is required.

pip install universal-ai-converter
pip install "universal-ai-converter[documents]"
pip install "universal-ai-converter[ocr]"
pip install "universal-ai-converter[media]"
pip install "universal-ai-converter[all]"

Until the first PyPI release, install directly from GitHub:

pip install "universal-ai-converter[all] @ git+https://github.com/KOLRNCH/Universal-AI-Converter.git"

OCR additionally requires the Tesseract executable. Video additionally requires FFmpeg. Both must be available in PATH.

For development from this repository:

python -m venv .venv
pip install -e ".[dev]"
pytest

Command line

uac convert report.pdf -o report.md
uac convert interview.mp4 -o transcript.md --whisper-model small
uac convert scan.png --format json -o result.json

Python

from universal_ai_converter import Converter

result = Converter().convert("report.pdf")
print(result.text)

HTTP API

pip install "universal-ai-converter[api,documents]"
uac serve --host 127.0.0.1 --port 8765
curl -F "file=@report.pdf" http://127.0.0.1:8765/convert

Any MCP-compatible agent

pip install "universal-ai-converter[mcp,documents]"
uac-mcp

Register uac-mcp as a stdio MCP server in the agent's configuration. The agent receives a convert_file tool. Exact configuration differs between clients, so examples for popular agents will live in docs/integrations/.

See the generic MCP setup for a reusable configuration example.

Docker

docker build -t universal-ai-converter .
docker run --rm -p 127.0.0.1:8765:8765 universal-ai-converter

Then upload a file to http://127.0.0.1:8765/convert. Model files downloaded by faster-whisper should be mounted in a persistent cache for repeated media conversions.

Format routing

Security

The HTTP server binds to localhost by default. Conversion libraries process untrusted files, so public deployments should run in an isolated container with file-size, time, CPU, and memory limits. Do not expose the development server directly to the internet.

Roadmap

• Plugin entry points for third-party converters

• Recursive archives and batch conversion

• URL and YouTube adapters

• Docker image and cross-platform desktop app

• Configurable OCR languages and timestamped transcripts

• Sandboxed production worker

License

MIT