toolbox-mcp

toolbox-mcp

An MCP server that gives AI agents real tools for the things it genuinely cannot do on its own. Read exact text from images and scans (OCR), process audio and video files, read and edit PDFs, work with images and Excel spreadsheets, run exact math, and more. Everything runs on your own machine over stdio. No network calls, nothing leaves your computer.

Inspired by the browser toolbox at footrue.com, reimplemented in Node so agents like Claude can call the same kind of tools directly.

Why

Modern models reason, see and code well, but there are whole categories they still cannot handle: they cannot open an audio or video file, they misread exact characters in an image, and they quietly get deterministic tasks (arithmetic, timezone math, regex) subtly wrong. This server hands those jobs to real, tested functions, so the agent gets the exact right answer, without burning tokens and without sending your data anywhere.

Two capabilities are worth calling out because a good model genuinely cannot do them at all:

• Audio and video — an LLM cannot open a media file. These tools inspect, convert, trim, and pull frames or audio from video, using a bundled ffmpeg (no install, no network).
• OCR — vision models describe images well but misread exact digits, serial numbers and table cells. ocr_image reads the real text with a local, offline model.

Tools

Reading images and media

Tool	What it does
ocr_image	Read the exact text from an image, screenshot or scan (offline OCR)
media_info	Duration, format, resolution, frame rate, codecs of audio/video
extract_audio	Pull the audio track out of a video
extract_frame	Grab a single frame from a video at a timestamp
video_to_gif	Turn a video (or a clip of it) into an animated GIF
trim_media	Cut a section out of audio or video
convert_media	Convert audio/video to another format
compress_video	Re-encode a video to shrink its size

PDF

Tool	What it does
pdf_extract_text	Pull the readable text out of a PDF so an agent can read it
pdf_merge	Merge several PDFs into one
pdf_split	Extract a page range into a new PDF
pdf_rotate	Rotate all pages by 90 / 180 / 270
images_to_pdf	Combine PNG/JPG images into a PDF, one per page
pdf_watermark	Stamp a diagonal text watermark across every page
pdf_info	Page count, title, author, file size

Files and office

Tool	What it does
xlsx_to_json	Read an Excel spreadsheet into JSON
json_to_xlsx	Write JSON rows to an Excel spreadsheet
zip_create	Zip a list of files into an archive
zip_extract	Extract a zip archive to a folder
html_to_markdown	Convert HTML (e.g. a scraped page) into clean Markdown
exif_read	Read a photo's EXIF metadata (camera, date, GPS)

Image

Tool	What it does
image_convert	Convert between png, jpeg, webp, avif, gif, tiff
image_resize	Resize by width and/or height with fit control
image_compress	Shrink file size at a chosen quality
image_rotate	Rotate by any angle
image_grayscale	Convert to black and white
image_crop	Crop a rectangular region
image_watermark	Overlay a text watermark
image_info	Format, dimensions, channels, file size

Compute (the things LLMs get wrong)

Tool	What it does
calculate	Evaluate a math expression exactly, including unit conversions
timezone_convert	Convert a date-time between IANA timezones
regex_extract	Apply a regex and return every match exactly
diff_text	Precise line-by-line diff of two texts
qr_generate	Generate a QR code PNG from text or a URL
qr_decode	Read the text or URL out of a QR code image
cron_describe	Explain a cron expression and list the next run times
password_generate	Generate a strong random password

Crypto and security

Tool	What it does
hash_text	md5 / sha1 / sha256 / sha384 / sha512 of text
hmac_sign	HMAC signature with a secret key
bcrypt_hash / bcrypt_verify	Hash and check passwords with bcrypt
generate_uuid	One or more random v4 UUIDs
jwt_decode	Decode a JWT header and payload (no signature check)

Data and text

Tool	What it does
format_json	Validate and pretty-print or minify JSON
csv_to_json	CSV into a JSON array of objects
convert_color	Hex color into RGB and HSL
base64_encode / base64_decode	Base64 both ways
url_encode / url_decode	Percent-encode and decode
slugify	Text into a clean URL slug
change_case	upper, lower, title, sentence, camel, snake, kebab, constant
text_stats	Word, character, sentence, line counts and reading time

PDF and image tools read and write files by path, so the agent can hand you a document and get a processed file back. Everything runs on your own machine.

Setup

toolbox-mcp is a standard stdio MCP server, so it works in any MCP client. The easiest way is npx, which downloads and runs it with no install or build step. Just add one of the configs below.

Claude Desktop / Cursor

Edit claude_desktop_config.json (Claude) or the MCP settings (Cursor):

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

VS Code (Copilot agent mode)

Create .vscode/mcp.json in your workspace, or run MCP: Open User Configuration from the Command Palette. Note that VS Code uses the servers key:

{
  "servers": {
    "toolbox": {
      "command": "npx",
      "args": ["-y", "toolbox-mcp"]
    }
  }
}

Google Antigravity

Open Settings > Customizations > Open MCP Config (this edits ~/.gemini/config/mcp_config.json), then add:

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

Save and hit refresh in the Installed MCP Servers section.

After configuring, restart or refresh the client and the tools appear automatically. Then just ask, for example, "read this PDF", "convert this image to webp", or "what is 90 km/h in m/s", and the agent will call the tool.

Run from source

To hack on it locally instead of using npx:

git clone https://github.com/medoxisto/toolbox-mcp
cd toolbox-mcp
npm install
npm run build   # or: npm run dev

Then point your client at node /absolute/path/to/toolbox-mcp/dist/index.js.

Privacy

Everything runs locally over stdio. There are no network requests and no telemetry. The compute, data and crypto tools are pure functions; the PDF and image tools read and write only the file paths you give them. Your data never leaves your machine.

Contributing

The toolbox is easy to extend: each tool is a small object with a name, description, a zod schema, and a handler that returns a string. See src/tools. PRs that add useful, deterministic, network-free tools are welcome.

License

MIT. See LICENSE.