Free the Tools

freethetools

在你自己的电脑上释放工具，供 AI 助手使用。你的文件永远不会离开电脑。

此软件包会运行一个 Model Context Protocol（MCP）服务和一个小型命令行工具，也可作为代码库使用。它们为 AI 助手提供不断扩充的日常文件处理工具，例如压缩、合并、拆分、旋转和解锁 PDF，去除照片中的位置信息，转换 CSV 和 JSON，以及生成哈希值。这些工具与 freethetools.com 上的工具相同。

它已作为 io.github.sapience-design/freethetools 列入官方 MCP Registry。

拥有此服务的助手无需再为这些任务安装 Ghostscript、ImageMagick 或 Python 软件包。服务会告诉它使用这些工具。

隐私承诺

• 服务在你的电脑上运行。它会从磁盘读取你指定的文件。
• 它不会自行建立网络连接。不会上传任何内容，也不会统计任何信息。
• 结果会保存在你电脑上的文件夹中（参见结果保存位置）。
• 每项任务的记录会保留质量等级或页面范围等选项，但绝不会保留你提供给工具的文本、密码或任何其他机密信息。
• 它只会读取和写入可安全交由助手处理的内容（参见安全性）。
• 助手读取或生成的所有内容都会经过你与它的对话。对于密码等机密信息，请使用网站，而不是助手。

设置

你需要安装 Node.js 22 或更高版本。无需安装其他内容：npx 会在首次使用时获取软件包。

Claude Code

在终端中运行一次：

claude mcp add freethetools -- npx -y freethetools mcp

在名称前添加 --scope user，即可在每个项目中使用。运行 claude mcp list 检查。

来源：Claude Code MCP 文档。

Claude Desktop

Claude Desktop 不会在你的项目文件夹中运行。请向助手提供绝对路径，例如 C:\Users\you\Documents\report.pdf 或 /Users/you/Documents/report.pdf。像 report.pdf 这样的短路径将无法找到文件。

1. 打开 Claude 菜单，然后依次选择 Settings、Developer 和 Edit Config。
2. 将以下内容添加到 claude_desktop_config.json（Windows：%APPDATA%\Claude，macOS：~/Library/Application Support/Claude）：

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

3. 重启 Claude Desktop。

来源：连接到本地 MCP 服务。在 Windows 上，如果应用无法启动 npx，请使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "freethetools", "mcp"]。

Cursor

将上文相同的 mcpServers 代码块添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）。来源：Cursor MCP 文档。

任何其他 MCP 客户端

使用以下命令启动服务，并通过标准输入和输出（stdio）进行 MCP 通信：

npx -y freethetools mcp

不使用 MCP

没有 MCP 的助手或脚本可以使用命令行：

npx -y freethetools list
npx -y freethetools run merge_pdfs '{"files":["a.pdf","b.pdf"]}'
npx -y freethetools run compress_pdf '{"file":"report.pdf","quality":"smallest","saveTo":"."}'
npx -y freethetools run convert_case '{"text":"hello world","case":"title"}'

run 会以 JSON 格式打印结果：ok、summary、data 以及保存的 files，并附上完整路径。如果任务失败，它会以代码 1 退出。在 Windows 上，请将 JSON 放入文件，并使用 @args.json 代替 JSON。运行 freethetools --help 查看全部内容。

在自己的代码中使用

使用 npm install freethetools 安装（需要 Node.js 22 或更高版本），然后从 JavaScript 或 TypeScript 调用任意工具。每个工具都是以其名称命名的函数：compress_pdf 对应 compressPdf。

import { compressPdf, mergePdfs, convertCase } from "freethetools";
import { readFile, writeFile } from "node:fs/promises";

const { files } = await compressPdf({ file: "report.pdf", quality: "smallest" });
await writeFile(files[0].name, files[0].bytes);

const merged = await mergePdfs({ files: ["a.pdf", await readFile("b.pdf")] });
const { data } = await convertCase({ text: "hello world", case: "title" });

• 输入文件可以是路径、字节数据（Uint8Array 或 Buffer）、Blob，也可以是 { name, bytes }。你的字节数据会被复制，绝不会被修改。路径的读取方式与命令行相同：隐藏文件和文件夹会被拒绝。
• 返回结果为 { tool, summary, data, files }。每个文件都包含 name、type、size 和 bytes。不会向磁盘写入任何内容，也不会在库文件夹中记录任何内容；由你决定要保存什么。
• 出错时会抛出带有普通错误消息的 FreeTheToolsError，例如 case should be one of: upper, lower, …。
• run(name, args) 按名称调用工具，listTools() 则以 JSON Schema 格式列出所有工具及其选项。
• 每次调用都会在独立线程中运行，并设有时间限制：60 秒；对于会启动引擎（如 Ghostscript）的工具，则为 300 秒。传入 { timeout: seconds } 作为第二个参数即可更改时间限制。
• 已包含类型定义，每个函数都附带该工具的说明，供你的编辑器使用。

所有操作都在你的计算机上运行，无需网络连接，与 MCP 服务一样。

工具

运行 freethetools list 查看完整列表。文件始终是你计算机上的路径，可以是绝对路径，也可以是相对于工作目录的路径。

分组	工具
PDF	compress_pdf, add_to_pdf, list_pdf_form_fields, fill_pdf_form, images_to_pdf, merge_pdfs, arrange_pdf_pages, protect_pdf, rotate_pdf, split_pdf, unlock_pdf
图像	remove_photo_metadata
文本	convert_case, compare_texts, count_words
数据	csv_to_json, json_to_csv, format_json
开发者	base64_encode, base64_decode, generate_hash, decode_jwt, generate_password, make_qr_code, test_regex, url_encode, url_decode, generate_uuids
日常	convert_colour, convert_time_zone, convert_units, convert_unix_timestamp

所有会生成文件的工具都支持可选参数 saveTo：指定另一个文件夹，将结果也保存到该文件夹中。绝不会覆盖现有文件；服务器会在文件名后添加“ (2)”。saveTo 有相关规则：请参阅安全性。

结果保存位置

内容	位置
库文件夹	主目录下名为 freethetools 的文件夹
另一个文件夹	freethetools mcp --library <folder>，或设置 FREETHETOOLS_LIBRARY
结果文件	<library>/files/<id>/<name>
每项任务的记录	<library>/library.jsonl，每行一条 JSON 记录

记录包含工具名称、时间、设置、输入文件名和大小、工具返回的简短摘要以及结果文件。失败的任务也会连同错误一起记录。

• 设置仅包含选项：是/否开关、数字、列表中的选项，以及少量简短值，例如文件名或页码范围。你提供给工具的文本、密码、机密信息（JWT 密钥、Wi-Fi 密码）和 saveTo 都不会被记录。
• 摘要为单行内容，例如“已编码 3 个字节”。摘要可能会包含你输入的内容，例如 Wi-Fi 网络名称。
• 记录中绝不会包含文件内容。

在 Chrome 和 Edge 中，freethetools.com 上的库页面可以打开此文件夹，让你查看助手执行的操作并再次获取结果。该页面会在浏览器中读取文件夹；不会上传任何内容。

安全

AI 助手会选择路径和文件名。此软件包不会信任这些选择。

读取

• 它绝不会读取隐藏文件或隐藏文件夹中的文件。以点号开头的名称即为隐藏名称。这包括 ~/.ssh、~/.aws、~/.gnupg、.env 和 .git。
• 它会先跟随链接，因此指向隐藏文件的链接也会被拒绝。
• 只有工作目录、资源库或主文件夹下的路径部分会经过检查。位于 .work 等文件夹中的项目仍可正常使用。
• 在对话中，工具最多返回 1 MB 的文本或数据。较大的数据会作为文件保存到资源库中，结果中会提供其路径。

使用 saveTo 保存

saveTo 只能指向以下位置之一中的文件夹：

1. 工作目录。若工作目录是主文件夹或驱动器根目录，则不适用。
2. 资源库文件夹。
3. 使用 --allow-save <folder> 允许的文件夹。可重复使用此选项来添加更多文件夹。也可以将 FREETHETOOLS_ALLOW_SAVE 设为文件夹列表，在 Windows 上以 ; 分隔，在其他系统上以 : 分隔。

saveTo 不能指向隐藏文件夹，例如 .git/hooks。它会先跟随链接，因此链接不能指向允许范围之外的位置。

要在 Claude Code 中允许某个文件夹：

claude mcp add freethetools -- npx -y freethetools mcp --allow-save ~/Documents/results

文件名

• 此软件包绝不会保存以点号开头或没有扩展名的文件。
• 它绝不会保存可运行程序或可自行启动的文件：.bat .cmd .com .exe .dll .msi .ps1 .psm1 .vbs .vbe .js .jse .wsf .wsh .hta .scr .pif .lnk .url .reg .sh .bash .zsh .command .desktop .app .jar .py .rb .pl .mjs .cjs .scpt .workflow .ps1xml .inf .cpl。
• 资源库中的文件也遵循此规则。错误信息会指出文件名，并要求提供其他名称。

限制

• 每次调用在 60 秒后停止；compress_pdf 则在 5 分钟后停止。这样可避免失控的任务让服务挂起。
• 每次调用最多可读取 2 GB 的输入文件。超过此大小的文件会被拒绝。
• 受密码保护的 PDF 必须先解锁。
• 网站上的某些工具尚未包含在此软件包中，因为它们依赖 Node 不具备的浏览器组件：
  • Image Compress、Convert and Resize、HEIC to JPG、Image to SVG 和 PDF to Images 通过浏览器的 canvas 读取或保存图片。它们需要一个可在 Node 中运行的图像引擎。
  • Video to GIF 从浏览器的视频播放器获取帧。它需要一个可在 Node 中运行的视频解码器。
  • Markdown to HTML 和 File Converter 需要浏览器的页面模型（DOM）或 canvas。

compress_pdf 的工作原理

compress_pdf 运行编译为 WebAssembly 的 Ghostscript（@jspawn/ghostscript-wasm）。WebAssembly 文件随此软件包一起提供（约 16 MB），因此无需下载，也无需在计算机上安装 Ghostscript。

许可证

与网站一样，采用 AGPL-3.0-only。源代码位于 github.com/sapience-design/freethetools。第三方代码列于 NOTICE 中。

一项 Sapience Design 倡议。