Rounder tools

@roundertools/mcp

一个 MCP 服务，为 AI 助手提供来自 roundertools.com 的文件工具：压缩、合并、拆分和保护 PDF，转换和调整图像大小，压缩文件，以及使用 ffmpeg 缩小、转换和剪辑视频。它通过 stdio 在你的电脑上运行。文件保留在原处，也不会发起网络请求。

安装

Claude Code：

claude mcp add roundertools -- npx -y @roundertools/mcp
claude mcp add roundertools --scope user -- npx -y @roundertools/mcp --allow ~/Documents --allow ~/Downloads

在 Claude Code 中，你或许根本不需要 MCP 服务。roundertools 插件（/plugin marketplace add adam-sari/rounder，然后运行 /plugin install roundertools@roundertools）是一项技能，可教 Claude 运行 CLI；在使用前约占用 100 个 token。

Claude Desktop（claude_desktop_config.json，位于“设置”→“开发者”→“编辑配置”中）：

{ "mcpServers": { "roundertools": { "command": "npx", "args": ["-y", "@roundertools/mcp", "--allow", "/Users/you/Documents"] } } }

在 Windows 上，如果找不到 npx，请使用 "command": "cmd", "args": ["/c", "npx", "-y", "@roundertools/mcp", …]。

Cursor（~/.cursor/mcp.json 或 .cursor/mcp.json）：

{ "mcpServers": { "roundertools": { "command": "npx", "args": ["-y", "@roundertools/mcp"] } } }

VS Code（.vscode/mcp.json）：

{ "servers": { "roundertools": { "type": "stdio", "command": "npx", "args": ["-y", "@roundertools/mcp"] } } }

需要 Node 22.13 或更高版本；当 ffmpeg 位于 PATH 中（或位于 ROUNDERTOOLS_FFMPEG 指定的位置）时，视频和音频工具才会显示。

它可能访问的内容

• 读取通过 --allow DIR（可重复指定）或 ROUNDERTOOLS_ALLOW（路径列表）指定文件夹中的内容。两者都未设置时，可读取你的主文件夹以及启动时所在的文件夹（如果该文件夹是项目目录而非系统文件夹）。客户端的根目录可以进一步缩小此范围，但不能扩大范围。
• 绝不读取隐藏文件夹和文件（.ssh、.aws、.config、.env……）、密钥和密码文件，或浏览器配置文件等应用数据，即使它们位于允许访问的文件夹中也不例外。路径必须是绝对路径；检查前会解析符号链接。唯一例外是服务自己的设置文件夹，服务启动时会读取该文件夹；任何工具调用都无法读取它。
• 写入仅限输入文件所在目录，或通过 --out DIR 指定的文件夹。它绝不会替换已有文件，也不会覆盖输入文件。另一个写入位置是服务自己的设置文件夹。
• **网络：**不使用网络。服务会先加载一个防护机制，在服务进程及其工作线程中屏蔽 fetch、http、https、net、tls、dgram 和 DNS 查询。在 Node 26 及更高版本中，服务还会在 Node 权限模型下重新运行自身，且不具备网络访问权限。在 Node 22 和 24 中，该防护并非沙箱；这项保证依赖于所用软件包不包含网络代码。ffmpeg 会作为独立程序运行，且其输入仅限本地文件（-protocol_whitelist file,pipe）。
• **访问磁盘前先行检查：**超出允许文件夹范围的路径会在查询之前被拒绝，因此工具调用无法探测哪些文件存在，也无法在 Windows 上让电脑连接到 \\server\share。

从文件中读取的文本和详细信息（文档转 Markdown、PDF 转文本、表单字段、PDF 标题、EXIF 字段）会作为文件内容返回，并置于文件无法猜出的随机名称标签之间，而不会被当作指令。

加载内容

客户端会在每次对话开始时，把服务列出的所有工具发送给模型，不论是否会用到。一次性列出所有 工具（使用 ffmpeg 时共 38 个）约需 18,000 个令牌。因此，默认情况下服务只列出三个辅助工具，约 700 个令牌， 再加一小段说明（约 150 个令牌）：

• find-tool：根据你想完成的任务搜索网站上的所有工具
• describe-tool：以 JSON Schema 格式查看任意工具的选项
• run-tool：使用相同的检查运行任何可在浏览器外运行的工具

这些辅助工具背后有 merge-pdf、split-pdf、compress-pdf、protect-pdf、unlock-pdf、organize-pdf、 add-page-numbers-to-pdf、watermark-pdf、jpg-to-pdf、pdf-to-text、extract-images-from-pdf、pdf-form-fields、 fill-pdf-form，使用 @napi-rs/canvas 时还有 pdf-to-jpg 和 redact-pdf，接着是 image-converter、image-compressor、 image-resizer、crop-image、rotate-image、exif-remover、image-prep、image-diff、zip-files、unzip-files、 checksum-calculator、file-info、document-to-markdown、spreadsheet-inspector，使用 ffmpeg 时还有 video-compressor、video-converter、trim-video、mute-video、video-to-gif、video-to-mp3、audio-converter、 video-contact-sheet，以及网站上其他可在浏览器外运行的工具。

列表会随着使用而扩展：

• 按工具添加。 助手使用 describe-tool 描述某个工具，或使用 run-tool 成功运行某个工具后，服务就会直接列出该工具，并通知客户端（notifications/tools/list_changed），这样下次就能按名称调用。find-tool 只负责搜索，运行失败不会添加工具。即使客户端忽略列表变更，也仍能通过 run-tool 使用所有工具；对于启动时未列出的工具，find-tool 和提示词都会指引使用 run-tool。每次列表变更都可能导致客户端重新读取列表（并丢失缓存的提示词），因此每个工具只会触发一次。
• 收藏工具。 过去 90 天内至少使用过两次的工具（最多五个），会在它们能在这台电脑上运行时从一开始就列出。请参阅记忆。

如果你更愿意一次性花费令牌来让助手搜索，可以使用 --tools all 在一开始列出所有工具。--tools default 会列出 0.1 版默认列出的工具集合（除了 checksum-calculator 之外的所有工具）。工具类别（--tools pdf,image）和工具名称（--tools compress-pdf,merge-pdf）只会列出指定工具。它们可以组合使用：--tools lean,pdf 或 --tools default,checksum-calculator。辅助工具始终可用。该标志的优先级高于设置文件，而设置文件的优先级高于精简默认设置。

每个工具都接受 inputs（绝对路径）、可选的 output（文件夹；若只有一个结果，也可以是新文件）以及各自的选项。结果会以摘要、指向文件的 resource_link，以及包含每个输出路径、大小和类型的 structuredContent 返回。图像工具可通过 preview: true 获取结果的小尺寸 PNG 预览。

在终端编码 Agent（Claude Code、Codex、Gemini CLI、opencode）中，第一次 find-tool 的结果会说明一次：无需使用 MCP，也可以通过 npx -y roundertools <tool> … 完成相同操作。其他功能均不受所连接客户端的影响。

提示词

选择提示词之前不会产生任何费用。每个提示词都会告诉助手要调用哪个工具，以及使用哪些参数。

提示词	参数
compress-pdf	file，可选的 size（例如 1mb）
merge-pdfs	files
convert-images	files、format
pdf-to-text	file
read-document	file（PDF、Word、PowerPoint、Excel 或 CSV）
fill-pdf-form	file（列出字段、询问你，然后填写）
redact-pdf	file、what（仅在使用 @napi-rs/canvas 时可用）
shrink-video	file，可选的 size（仅在使用 ffmpeg 时可用）

记忆

收藏项根据你使用工具的次数生成。工具成功运行后，服务会将其计数加 1，并在 usage.json 中记录日期：

{ "version": 1, "tools": { "compress-pdf": { "count": 4, "last": "2026-11-02" } } }

仅存储工具名称、计数和日期，不会存储路径、文件名、选项或从文件中读取的任何内容。和其他内容一样，数据保留在你的电脑上。

使用 --no-memory、ROUNDERTOOLS_MEMORY=off 或 npx roundertools config set memory off 关闭此功能。使用 npx roundertools config reset 清除所有数据。

设置

settings.json 和 usage.json 位于同一个文件夹中：

系统	文件夹
Windows	%APPDATA%\roundertools
macOS	~/Library/Application Support/roundertools
Linux 和其他系统	$XDG_CONFIG_HOME/roundertools，或 ~/.config/roundertools

ROUNDERTOOLS_CONFIG_DIR 可指定其他文件夹。CLI 可查看和修改这些设置：

npx roundertools config                  # the folder, the settings and your favourites
npx roundertools config set tools all    # lean, all, default, families or tool names
npx roundertools config set memory off   # on or off
npx roundertools config reset            # remove both files

更改会在下次启动服务时生效，命令行上的标志具有更高优先级。在 Node 26 及更高版本中，权限模型允许服务读写此文件夹，因此记忆功能也可以正常工作。关闭记忆功能后，服务可能只能读取该文件夹。

选项

选项
--allow DIR	允许读取的文件夹（可重复指定）
--out DIR	允许写入的文件夹，输入文件所在位置除外
--tools LIST	lean（默认）、all、default、工具类别（pdf,image,files,media）或工具名称
--no-memory	不统计你使用的工具
--experimental	启用尚未完成的功能（目前尚无）
--max-input SIZE	单文件限制（默认 1gb，媒体文件为 2gb）
--timeout MIN	每次调用的分钟数（默认 5，媒体文件为 30）
--max-outputs N	单次调用可写入的文件数（默认 500）

基于官方 MCP TypeScript SDK（@modelcontextprotocol/server）构建；仅支持 stdio；日志写入 stderr；一次运行一个耗时任务；发送进度通知；调用取消后停止。

许可证

MIT。文档：roundertools.com/developers/mcp。源代码位于 packages/mcp： github.com/adam-sari/rounder。