Content
# toolbox-mcp
An [MCP](https://modelcontextprotocol.io) 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](https://footrue.com), reimplemented in Node so agents like **Claude** can call the same kind of tools directly.
[](https://www.npmjs.com/package/toolbox-mcp)
[](LICENSE)
[](https://modelcontextprotocol.io)
## 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):
```json
{
"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:
```json
{
"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:
```json
{
"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`:
```bash
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](https://zod.dev) schema, and a handler that returns a string. See [`src/tools`](src/tools). PRs that add useful, deterministic, network-free tools are welcome.
## License
MIT. See [LICENSE](LICENSE).
