MCP server for local file conversion, analysis, and image processing. Images, audio, video, documents, and structured data -- all processed locally, nothing uploaded anywhere.
44 supported formats across 5 categories. 7 tools for converting, analyzing, processing, merging, and generating files.
npx overtooled-mcpOr install globally:
npm install -g overtooled-mcpRequires Node.js >= 18.
Add to your MCP settings:
{
"mcpServers": {
"overtooled": {
"command": "npx",
"args": ["-y", "overtooled-mcp"]
}
}
}Add to .cursor/mcp.json:
{
"mcpServers": {
"overtooled": {
"command": "npx",
"args": ["-y", "overtooled-mcp"]
}
}
}Convert a file from one format to another.
| Parameter | Type | Required | Description |
|---|---|---|---|
input_path |
string | Yes | Absolute path to the source file |
output_format |
string | Yes | Target format as MIME type (image/png) or extension (png) |
output_path |
string | No | Output file path. Defaults to input location with new extension |
options |
object | No | Format-specific options (e.g. { quality: 80 }) |
input_path: "/photos/vacation.heic"
output_format: "jpg"
options: { quality: 90 }
Returns the output path, input/output sizes, and format-specific metadata (dimensions for images, duration for audio/video, etc.).
Get detailed metadata about any file. For images: dimensions, color space, DPI, EXIF. For audio/video: duration, codec, bitrate, sample rate. For all files: size, format detection, entropy.
| Parameter | Type | Required | Description |
|---|---|---|---|
input_path |
string | Yes | Absolute path to the file to analyze |
include_exif |
boolean | No | Include full EXIF data for images (default: true) |
input_path: "/photos/sunset.jpg"
Example output:
{
"file": "sunset.jpg",
"size": 2457600,
"sizeHuman": "2.3 MB",
"format": "image/jpeg",
"category": "image",
"entropy": 7.45,
"width": 3840,
"height": 2160,
"colorSpace": "srgb",
"dpi": 72,
"exif": { "Make": "Canon", "Model": "EOS 5D", "FocalLength": 50 }
}For audio/video files, returns duration, codec, bitrate, sample rate, channels, and stream details.
Apply one or more image operations: resize, compress, rotate, flip, blur, sharpen, grayscale, negate, strip metadata, or change format. Operations are chained in order.
| Parameter | Type | Required | Description |
|---|---|---|---|
input_path |
string | Yes | Absolute path to the source image |
output_path |
string | No | Output path. Defaults to input_processed.[ext] |
operations |
array | Yes | Array of operations to apply in order (min 1) |
Operations:
| Type | Parameters | Description |
|---|---|---|
resize |
width, height, fit |
Scale image. fit: cover, contain, fill, inside (default), outside |
compress |
quality (1-100, default 80) |
Reduce file size |
rotate |
angle (degrees) |
Rotate by arbitrary angle |
flip |
-- | Flip vertically |
flop |
-- | Flip horizontally |
blur |
sigma (0.3-100, default 3) |
Gaussian blur |
sharpen |
sigma (default 1) |
Sharpen edges |
grayscale |
-- | Convert to grayscale |
negate |
-- | Invert colors |
strip_metadata |
-- | Remove EXIF and other metadata |
format |
format, quality |
Convert to jpeg, png, webp, tiff, or avif |
input_path: "/photos/large.jpg"
operations: [
{ type: "resize", width: 1280 },
{ type: "compress", quality: 75 },
{ type: "format", format: "webp" }
]
Combine multiple files into one. Supports PDF merging, images-to-PDF, text concatenation, and CSV merging.
| Parameter | Type | Required | Description |
|---|---|---|---|
input_paths |
array | Yes | Array of absolute file paths (min 2) |
output_path |
string | Yes | Absolute path for the merged output |
mode |
string | No | auto (default), pdf_merge, images_to_pdf, concatenate, csv_merge |
options.separator |
string | No | Separator between concatenated files (default: newline) |
options.page_size |
string | No | PDF page size: a4 (default), letter, legal |
options.landscape |
boolean | No | Landscape orientation for PDF (default: false) |
Auto-detection: all PDFs -> pdf_merge, all images -> images_to_pdf, all CSVs -> csv_merge, otherwise -> concatenate.
input_paths: ["/docs/ch1.pdf", "/docs/ch2.pdf", "/docs/ch3.pdf"]
output_path: "/docs/combined.pdf"
Generate placeholder/test files from scratch. No input file needed.
| Parameter | Type | Required | Description |
|---|---|---|---|
type |
string | Yes | text, image, audio, video, or data |
output_path |
string | Yes | Absolute path for the generated file |
Text options (lorem ipsum):
| Parameter | Type | Default | Description |
|---|---|---|---|
text_mode |
string | paragraphs |
paragraphs, sentences, or words |
text_count |
number | 3 | Number of units to generate |
Image options (placeholder with dimensions label, requires sharp):
| Parameter | Type | Default | Description |
|---|---|---|---|
width |
number | 800 | Width in pixels (max 4096) |
height |
number | 600 | Height in pixels (max 4096) |
bg_color |
string | #cccccc |
Background color (hex) |
text_color |
string | #666666 |
Text color (hex) |
label |
string | WIDTHxHEIGHT |
Custom text overlay |
image_format |
string | png |
png, jpeg, or webp |
quality |
number | 92 | Quality for JPEG/WebP (1-100) |
Audio options (WAV, pure JS -- no ffmpeg needed):
| Parameter | Type | Default | Description |
|---|---|---|---|
audio_type |
string | tone |
tone, noise, chirp, or silence |
frequency |
number | 440 | Tone frequency in Hz |
duration |
number | 3 | Duration in seconds (max 30) |
sample_rate |
number | 44100 | Sample rate |
waveform |
string | sine |
sine, square, sawtooth, or triangle |
Video options (MP4/WebM with test patterns, requires ffmpeg):
| Parameter | Type | Default | Description |
|---|---|---|---|
width |
number | 640 | Width in pixels (max 1920) |
height |
number | 480 | Height in pixels (max 1080) |
duration |
number | 3 | Duration in seconds (max 30) |
fps |
number | 30 | Frames per second (max 60) |
video_format |
string | mp4 |
mp4 or webm |
video_pattern |
string | solid |
solid, counter, gradient, or bars (SMPTE) |
bg_color |
string | #336699 |
Background color (hex) |
text_color |
string | #ffffff |
Text color (hex) |
Data options (mock JSON/CSV):
| Parameter | Type | Default | Description |
|---|---|---|---|
data_format |
string | json |
json or csv |
data_preset |
string | user-profile |
user-profile, address-book, employee-list, or products |
row_count |
number | 10 | Number of rows (max 1000) |
type: "image"
output_path: "/tmp/placeholder.png"
width: 1280
height: 720
label: "Hero Image"
type: "audio"
output_path: "/tmp/test-tone.wav"
audio_type: "tone"
frequency: 1000
duration: 5
waveform: "square"
List all supported formats, optionally filtered by category or by what a given input format can convert to.
| Parameter | Type | Required | Description |
|---|---|---|---|
category |
string | No | Filter by category: image, audio, video, text, document |
input_format |
string | No | Show only formats this input can convert to (MIME or extension) |
category: "image"
input_format: "csv" # shows what CSV can convert to
Get available options and their defaults for a specific output format.
| Parameter | Type | Required | Description |
|---|---|---|---|
output_format |
string | Yes | Target format as MIME type or extension |
output_format: "mp3"
Returns format info plus configurable options (quality, bitrate, compression level, etc.).
| Format | Input | Output | Options |
|---|---|---|---|
| PNG | yes | yes | -- |
| JPEG | yes | yes | quality: 1-100 (default 92) |
| WebP | yes | yes | quality: 1-100 (default 80) |
| GIF | yes | -- | -- |
| BMP | yes | -- | -- |
| SVG | yes | -- | -- |
| HEIC | yes | -- | -- |
| HEIF | yes | -- | -- |
| TIFF | yes | yes | -- |
| Format | Input | Output | Options |
|---|---|---|---|
| WAV | yes | yes | bitDepth: 16/24/32 |
| MP3 | yes | yes | bitrate: 128/192/256/320 kbps |
| FLAC | yes | yes | compressionLevel: 0-8 |
| OGG | yes | -- | -- |
| AAC | yes | yes | bitrate: 128/192/256/320 kbps |
| M4A | yes | yes | bitrate: 128/192/256/320 kbps |
| Opus | yes | yes | bitrate: 64/128/192/256 kbps |
| AIFF | yes | yes | bitDepth: 16/24/32 |
| Format | Input | Output | Options |
|---|---|---|---|
| MP4 | yes | yes | crf: 0-51 (default 28), preset, maxHeight |
| WebM | yes | yes | crf: 0-63 (default 32), preset, maxHeight |
| MOV | yes | yes | crf: 0-51 (default 28), preset, maxHeight |
| AVI | yes | -- | -- |
| MKV | yes | yes | crf: 0-51 (default 28), preset, maxHeight |
| MPEG-TS | yes | yes | crf: 0-51 (default 28), preset, maxHeight |
| GIF | -- | yes | fps: 5-30 (default 10), maxHeight |
Video options: preset (ultrafast/fast/medium/slow), maxHeight (4K/1440/1080/720/480/360), stripAudio (boolean).
| Format | Input | Output | Options |
|---|---|---|---|
| JSON | yes | yes | indent: 0-8 (default 2) |
| CSV | yes | yes | delimiter: comma/semicolon/pipe |
| TSV | yes | yes | -- |
| XML | yes | yes | indent: 0-8 (default 2) |
| YAML | yes | yes | -- |
| TOML | yes | yes | -- |
| INI | yes | yes | -- |
| XLSX | yes | yes | -- |
| SQL | -- | yes | tableName, dialect: insert/create-insert |
| Format | Input | Output |
|---|---|---|
| Markdown | yes | yes |
| HTML | yes | yes |
| Plain Text | yes | yes |
| Format | Input | Output | Notes |
|---|---|---|---|
| yes | yes | Also converts to images or plain text | |
| DOCX | yes | -- | Converts to PDF |
| PPTX | yes | -- | Converts to PDF |
| ODT | yes | -- | Converts to PDF |
| ODP | yes | -- | Converts to PDF |
| ODS | yes | -- | Converts to PDF |
| RTF | yes | -- | Converts to PDF |
Cross-category: All images, structured data, and markup can also convert to PDF.
- Within category: Any input -> all outputs in the same category (excluding same format)
- To PDF: Images, structured data, and markup can all convert to PDF
- From PDF: PDF -> images (first page rendered) or plain text (extracted)
- Documents -> PDF: DOCX, PPTX, ODT, ODP, ODS, RTF all convert to PDF only
- No cross-category: Audio cannot convert to images, video cannot convert to data, etc.
Required (installed automatically): Text and data conversion works out of the box.
Optional (install for full format support):
| Package | Enables | Install |
|---|---|---|
sharp |
Image conversion and analysis | npm install sharp |
ffmpeg-static |
Audio/video conversion | npm install ffmpeg-static |
canvas |
PDF-to-image rendering | npm install canvas |
If ffmpeg-static is not installed, the server looks for ffmpeg in your system PATH.
Missing optional dependencies produce clear error messages telling you what to install.
Ported from Overtooled -- a 179-tool browser utility suite. The conversion engines were adapted from client-side (Canvas, Web Audio, WebCodecs) to Node.js (sharp, FFmpeg, PDFKit).
src/
server.ts # MCP server + tool registration
tools/ # 7 tool handlers
convert-file.ts
analyze-file.ts
process-image.ts
merge-files.ts
generate-file.ts
list-formats.ts
get-options.ts
engines/ # Conversion engines by category
engine-image.ts # sharp
engine-audio.ts # FFmpeg CLI
engine-video.ts # FFmpeg CLI
engine-text.ts # Pure JS
engine-pdf.ts # PDFKit + pdfjs-dist + mammoth
registry/
format-registry.ts # Format definitions + conversion matrix
utils/
mime.ts # MIME detection from extension
ffmpeg.ts # FFmpeg binary resolution
ffprobe.ts # Media metadata extraction via ffprobe
magic-bytes.ts # File type detection by header bytes
- Text engine: Pure JS. JSON, CSV, XML, YAML, TOML, INI, SQL, XLSX, Markdown, HTML. Two-stage conversion: parse input -> JS objects -> serialize output.
- Image engine: sharp for decode/encode. Handles HEIC, TIFF, SVG natively.
- Audio engine: FFmpeg CLI with codec selection and bitrate/quality mapping. 5-minute timeout.
- Video engine: FFmpeg CLI with CRF quality, resolution scaling, GIF palette generation. 10-minute timeout.
- PDF engine: PDFKit for generation, pdfjs-dist for text extraction, mammoth for DOCX, pdf-lib for merging.
npm run build # Compile TypeScript
npm run dev # Watch mode
npm test # Run tests (vitest)
npm run test:watch # Watch mode tests
npm run lint # Type checkMIT