overtooled-mcp

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.

Install

npx overtooled-mcp

Or install globally:

npm install -g overtooled-mcp

Requires Node.js >= 18.

Configure

Claude Code / Claude Desktop

Add to your MCP settings:

{
  "mcpServers": {
    "overtooled": {
      "command": "npx",
      "args": ["-y", "overtooled-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "overtooled": {
      "command": "npx",
      "args": ["-y", "overtooled-mcp"]
    }
  }
}

Tools

convert_file

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.).

---

analyze_file

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.

---

process_image

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" }
]

---

merge_files

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_file

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_formats

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_conversion_options

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.).

Supported Formats

Images (9 input, 4 output)

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	--

Audio (8 input, 7 output)

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

Video (6 input, 6 output)

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).

Data (9 input, 10 output)

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

Markup

Format	Input	Output
Markdown	yes	yes
HTML	yes	yes
Plain Text	yes	yes

Documents (7 input, 1 output)

Format	Input	Output	Notes
PDF	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.

Conversion Rules

• 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.

Dependencies

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.

Architecture

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

Engines

• 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.

Development

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 check

License

MIT