freetool-mcp

Model Context Protocol (MCP) server for FreeTool. Gives Claude Desktop, Claude Code, and Cursor direct access to FreeTool's PDF, text, and QR utilities — without leaving the AI chat.

All native tools run locally in Node. Files are read from and written to the local filesystem only; nothing is uploaded to a server.

Installation

Ad-hoc via npx (recommended — no install step):

npx -y freetool-mcp

Or install globally:

npm install -g freetool-mcp
freetool-mcp

Requires Node.js 18+.

Client configuration

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

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

Restart Claude Desktop. The 29 FreeTool tools will appear in the tool picker.

Claude Code

Add to your MCP servers list:

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

Or use the CLI:

claude mcp add freetool npx -y freetool-mcp

Cursor

In Settings → MCP, add:

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

Tool inventory

Native tools (run locally)

| Tool | Category | Description | |---|---|---| | pdf_merge | PDF | Merge multiple PDFs into one | | pdf_split | PDF | Split a PDF by page ranges | | pdf_rotate | PDF | Rotate pages by 90/180/270 degrees | | pdf_page_numbers | PDF | Add page numbers | | pdf_watermark | PDF | Add diagonal text watermark to every page | | pdf_lock | PDF | Password-protect a PDF (AES) | | pdf_unlock | PDF | Remove password protection (requires consent: true) | | pdf_extract_text | PDF | Extract embedded text via pdf.js | | text_character_count | Text | Count chars, bytes, words, lines | | text_json_format | Text | Format or minify JSON | | text_csv_to_json | Text | Convert CSV to JSON | | text_base64 | Text | Base64 encode/decode | | text_diff | Text | Unified line-by-line diff | | text_remove_whitespace | Text | Strip/collapse whitespace | | qr_generate | Utility | Generate QR code as PNG or SVG |

URL recommendation tools (browser-only)

These tools rely on browser-side WASM (ffmpeg.wasm, Tesseract.js, libheif, ONNX models, etc.) and are not available in the Node server. Calling them returns a link to the in-browser version on freetool.jp, which processes everything locally without any upload.

| Tool | Browser page | |---|---| | image_heic_to_jpg | https://freetool.jp/image/heic-to-jpg | | image_compress | https://freetool.jp/image/compress | | image_resize | https://freetool.jp/image/resize | | image_png_to_jpg | https://freetool.jp/image/png-to-jpg | | image_webp_to_png | https://freetool.jp/image/webp-to-png | | image_to_webp | https://freetool.jp/image/to-webp | | image_remove_bg | https://freetool.jp/image/remove-bg | | image_ocr | https://freetool.jp/image/ocr | | image_upscale | https://freetool.jp/image/upscale | | image_exif_remove | https://freetool.jp/image/exif-remove | | image_favicon | https://freetool.jp/image/favicon | | video_to_mp3 | https://freetool.jp/video/to-mp3 | | video_compress | https://freetool.jp/video/compress | | audio_transcribe | https://freetool.jp/audio/transcribe |

File I/O convention

Binary tools (PDF, QR) follow a consistent convention:

• Inputs: input_path (or input_paths) — absolute local file path(s).
• Outputs: output_path (or output_dir) — absolute target. If omitted, the server writes to a sensible default next to the input or to the OS temp dir, and returns the actual path in the response.

Text tools accept and return strings inline. pdf_extract_text returns text inline and truncates at 50,000 characters with a clear notice.

Privacy

• Native tools read and write local files only.
• No telemetry, no remote upload, no network calls (with the trivial exception of the URL-recommendation tools, which just return a URL string).
• For browser-only tools, the linked freetool.jp pages also run entirely in your browser — files never leave your device.

Sensitive operation: pdf_unlock

Removing password protection from a PDF you do not own may violate copyright law (e.g. DMCA §1201) and the terms under which the PDF was distributed. pdf_unlock therefore requires an explicit consent: true parameter; without it, the call is refused. This mirrors the consent gate on the freetool.jp web UI.

Development

git clone https://github.com/tatsuabe69/freetool.git
cd freetool
npm install --legacy-peer-deps
cd mcp
npm run build
npm run start

The dev script runs the server with tsx watch for fast iteration.

License

MIT. See the main FreeTool repository for issues and contributions.