通过模型上下文协议 (MCP) 将 AI 编码助手连接到 GetWebP 图像转换。

GetWebP MCP 服务器

通过模型上下文协议 (MCP) 将 AI 编码助手连接到 GetWebP 图像转换。

状态：即将推出 -- MCP 服务器 (@getwebp/mcp-server) 已实现并在测试中。它将在未来 CLI 版本的同时发布到 npm。下面描述的工具接口是稳定的，反映了当前的代码库。

什么是 MCP？#

MCP（模型上下文协议）是一个开放标准，让 AI 代理直接调用本地工具。与其为您生成要复制粘贴的 shell 命令相比，具有 MCP 访问权限的代理可以自行转换图像、扫描目录并检查许可证状态。

无 MCP	具有 MCP
代理生成 shell 命令，您手动运行它	代理直接调用 `convert_images`
您运行 `--dry-run` 并将输出粘贴回来	代理调用 `scan_images` 并读取结构化 JSON
您检查 `getwebp status` 并转述结果	代理调用 `get_status` 并自主决定

工具 #

MCP 服务器公开三个工具。所有工具都返回 AI 代理可以直接解析的结构化 JSON。

`convert_images`#

将图像 (JPG、PNG、BMP、WebP) 转换为优化的 WebP 格式。

参数：

参数	类型	必需	默认值	描述
`input`	string	是	--	输入文件或目录路径（绝对或相对）
`output`	string	否	与源相同	已转换文件的输出目录
`quality`	number	否	`80`	WebP 质量，1-100
`recursive`	boolean	否	`false`	递归处理子目录
`skip_existing`	boolean	否	`false`	跳过已有 `.webp` 版本的文件

响应：

{
  "success": true,
  "plan": "pro",
  "total": 3,
  "succeeded": 3,
  "failed": 0,
  "skipped": 0,
  "warnings": [],
  "results": [
    {
      "file": "/path/to/photo.jpg",
      "status": "success",
      "original_size": 204800,
      "new_size": 133120,
      "saved_ratio": 0.35
    }
  ]
}

在免费计划上，当至少处理了一个文件时，响应包括指向 getwebp.com/pricing 的 upgrade_url 字段。

注意：

相对路径相对于 MCP 服务器进程的工作目录解析。
免费计划：每次运行最多 20 个文件，每个文件间有 3 秒延迟（总时间可能超过 60 秒）。
付费计划：无限制文件，具有并行处理。

`scan_images`#

扫描目录以查找可转换的图像文件，而不修改任何内容。

参数：

参数	类型	必需	默认值	描述
`path`	string	是	--	要扫描的目录或文件路径（绝对或相对）
`recursive`	boolean	否	`false`	递归扫描子目录

响应：

{
  "total": 4,
  "files": [
    {
      "path": "/project/images/hero.jpg",
      "size": 204800,
      "format": "jpg",
      "has_webp": false
    },
    {
      "path": "/project/images/logo.png",
      "size": 51200,
      "format": "png",
      "has_webp": true
    }
  ]
}

has_webp 字段指示同一目录中是否已存在同名的 .webp 文件。format 字段将 .jpeg 规范化为 jpg。

`get_status`#

检查当前许可证状态和计划限制。不需要参数。

响应：

{
  "activated": true,
  "expired": false,
  "plan": "pro",
  "expires_at": "2027-04-01T00:00:00.000Z",
  "limits": {
    "max_files_per_run": null,
    "concurrent_workers": 7,
    "cooldown_seconds": 0
  }
}

字段	描述
`activated`	是否当前有活跃许可证
`expired`	仅当先前激活的许可证已过期时为 `true`
`plan`	`"free"` 或 `"pro"`
`expires_at`	ISO 8601 过期日期（免费计划上省略）
`limits.max_files_per_run`	免费计划上为 `20`，付费计划上为 `null`（无限制）
`limits.concurrent_workers`	免费计划上为 `1`，付费计划上为 CPU 核心数 - 1
`limits.cooldown_seconds`	免费计划上为 `3`，付费计划上为 `0`

安装 #

前提条件 #

Node.js 18 或更高版本
许可证（可选）： MCP 服务器与 CLI 共享本地配置，位于 ~/.config/getwebp/config.json。如果您已通过 getwebp auth <key> 激活许可证，MCP 服务器会自动识别它。没有许可证，它在免费计划上运行。

Claude Desktop #

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或您的操作系统上的等效路径：

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

保存后重新启动 Claude Desktop。

Cursor #

编辑 ~/.cursor/mcp.json：

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

其他 MCP 客户端 #

任何支持 stdio 传输的 MCP 客户端都可以连接。指向它：

npx -y @getwebp/mcp-server

更快启动（可选）#

npx 在首次运行时下载包，由于捆绑的 WASM 依赖，可能很慢。对于更快的冷启动，全局安装：

npm install -g @getwebp/mcp-server

然后在您的配置中替换 command 和 args：

{
  "mcpServers": {
    "getwebp": {
      "command": "getwebp-mcp"
    }
  }
}

集成示例 #

Claude Desktop #

配置后，您可以要求 Claude 直接处理图像：

"将 ./src/assets 中的所有图像转换为质量为 90 的 WebP。"

Claude 将调用 convert_images，使用 {"input": "./src/assets", "quality": 90}，并报告结果，包括文件大小和压缩比率。

"我的项目中哪些图像还没有被转换为 WebP？"

Claude 将调用 scan_images，使用 {"path": ".", "recursive": true}，并按 has_webp: false 过滤结果。

"我在免费计划上吗？"

Claude 将调用 get_status 并告诉您当前计划、限制和过期日期。

Cursor #

Cursor 的代理模式可以在代码生成工作流中使用 GetWebP 工具：

代理使用 scan_images 扫描项目以查找未转换的图像。
它使用 convert_images 转换它们。
它更新源代码中的 <img> 标签以引用新的 .webp 文件。

典型代理工作流 #

1. get_status        -- 检查计划和限制
2. scan_images       -- 发现可转换的文件
3. convert_images    -- 转换文件
4. 报告结果         -- 向用户总结节省情况

架构 #

MCP 服务器直接重用 CLI 的核心模块（不通过子进程），确保相同的转换行为：

AI 客户端 (Claude Desktop / Cursor / ...)
        | stdio (JSON-RPC)
        v
   MCP 服务器 (Node.js)
        |-- convert_images  --> processImages()      (cli/core/processor.ts)
        |-- scan_images     --> collectImageFiles()   (cli/core/file-scanner.ts)
        |-- get_status      --> checkLicense()        (cli/core/license.ts)

传输： stdio（标准 MCP 传输，普遍支持）
运行时： Node.js >= 18
包： @getwebp/mcp-server (npm)
二进制： getwebp-mcp

免费 vs 付费计划 #

计划限制在 MCP 服务器和 CLI 中的应用方式相同。

限制	免费	Pro
每次运行的文件数	20	无限制
处理延迟	每个文件 3 秒	无
并行工作者	1	自动 (CPU 核心数 - 1)

要升级，请在 getwebp.com/pricing 购买许可证并激活它：

getwebp auth <your-license-key>

MCP 服务器在其下次工具调用时自动获取新许可证。

故障排除 #

服务器不被客户端检测到 #

验证已安装 Node.js >= 18：node --version
检查配置文件路径对您的客户端是否正确。
编辑配置后重新启动客户端应用程序。
手动测试：npx -y @getwebp/mcp-server 应该无输出启动（它通过 stdio 通信）。

首次调用很慢 #

WASM 编解码器在首次转换时初始化。同一服务器会话中的后续调用很快。

免费计划超时 #

使用每个文件 3 秒的延迟，转换 20 个文件大约需要 60 秒。某些 MCP 客户端可能有需要为免费计划使用进行调整的超时设置。

许可证未被识别 #

MCP 服务器从 ~/.config/getwebp/config.json 读取。确保您已在同一台机器上激活您的许可证：

getwebp auth <your-key>
getwebp status   # 验证激活

链接 #

网站： getwebp.com
定价： getwebp.com/pricing
CLI 文档： README
MCP 协议： modelcontextprotocol.io

文档

GetWebP MCP 服务器