ZIP MCP Server

ZIP MCP Server

中文 | 英文

项目介绍

ZIP MCP Server 是一个基于 fastMCP 和 zip.js 构建、实现了模型上下文协议（MCP）的压缩服务。本项目提供完全可通过参数控制的 ZIP 压缩、解压缩和查询压缩包信息功能。

功能

• 支持压缩和解压缩文件及数据
• 支持多个文件打包压缩
• 提供压缩级别控制（0-9）
• 支持密码保护和加密强度设置
• 提供压缩包元数据查询功能
• 解压缩时验证 ZIP 条目路径，防止路径遍历写入

安全性

1.0.6 及更高版本修复了 decompress 工具中的任意文件写入问题：恶意 ZIP 条目名称（例如 ../outside.txt）此前可能与输出目录拼接，导致文件被写入预期解压根目录之外。现在，解压缩时会先解析输出根目录，再验证每个条目路径，并拒绝绝对路径、盘符路径、.. 路径段，以及任何会逃逸输出目录的路径。

感谢 Ryan（[email protected]）负责任地报告此问题。

项目结构

zip-mcp
├── src
│   ├── index.ts               # Application entry point
│   ├── utils
│   │   ├── compression.ts     # Compression and decompression implementation
│   │   └── safePath.ts        # Safe ZIP entry path validation
├── tsconfig.json              # TypeScript configuration file
├── package.json               # npm configuration file
└── README.md                  # Project documentation

安装

你可以使用 npm 全局安装 ZIP MCP Server：

npm install -g zip-mcp

MCP 配置

安装后，你可以在 MCP JSON 配置中配置 ZIP MCP：

{
  "mcpServers": {
    "zip-mcp": {
      "command": "zip-mcp",
      "args": []
    }
  }
}

在 AI 客户端中配置 MCP JSON

• Claude 客户端：https://modelcontextprotocol.io/quickstart/user
• Raycast：需要安装 MCP 插件
• Cursor：https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers

MCP 工具说明

ZIP MCP Server 提供以下工具，可通过 MCP 协议调用：

压缩工具（compress）

将本地文件或目录压缩为 ZIP 文件。

参数：

• input：要压缩的文件或目录路径（字符串或字符串数组）
• output：输出 ZIP 文件的路径
• options：压缩选项（可选）
  • level：压缩级别（0-9，默认值为 5）
  • password：密码保护
  • encryptionStrength：加密强度（1-3）
  • overwrite：是否覆盖现有文件（布尔值）

返回：

• 成功：包含成功信息的文本内容
• 失败：包含错误信息的文本内容

解压缩工具（decompress）

将本地 ZIP 文件解压缩到指定目录。写入前会验证条目路径，确保文件无法通过 .. 或绝对路径解压到 output 目录之外。

参数：

• input：ZIP 文件的路径
• output：输出目录的路径
• options：解压缩选项（可选）
  • password：解压缩密码
  • overwrite：是否覆盖现有文件（布尔值）
  • createDirectories：是否创建不存在的目录（布尔值）

返回：

• 成功：包含解压缩结果信息的文本内容
• 失败：包含错误信息的文本内容

ZIP 信息工具（getZipInfo）

获取本地 ZIP 文件的元数据信息。

参数：

• input：ZIP 文件的路径
• options：选项（可选）
  • password：解压缩密码

返回：

• 成功：包含 ZIP 文件详细信息的文本内容，包括：
  • 文件总数
  • 总大小
  • 压缩后大小
  • 压缩率
  • 每个文件的详细信息
• 失败：包含错误信息的文本内容

测试工具（echo）

返回输入的消息，以测试服务是否正常运行。

参数：

• message：要返回的消息

返回：

• 包含输入消息和当前时间戳的文本内容

示例

使用 MCP 客户端调用工具的示例：

// Compress files
await client.executeTool("compress", {
  input: "/path/to/files/or/directory",
  output: "/path/to/output.zip",
  options: {
    level: 9,
    comment: "Test compression",
    password: "secret",
    overwrite: true,
  },
});

// Decompress files
await client.executeTool("decompress", {
  input: "/path/to/archive.zip",
  output: "/path/to/extract/directory",
  options: {
    password: "secret",
    overwrite: true,
    createDirectories: true,
  },
});

// Get ZIP info
await client.executeTool("getZipInfo", {
  input: "/path/to/archive.zip",
  options: {
    password: "secret",
  },
});

// Test service
await client.executeTool("echo", {
  message: "Hello, ZIP MCP Server!",
});

联系方式

• 电子邮件：[email protected]
• 博客：https://7gugu.com