使用说明

图像MCP服务器

使用FastMCP构建的用于图像处理的综合模型上下文协议（MCP）服务器。此服务器为LLM提供了强大的图像功能，包括检索、转换、调整大小和元数据提取。

特性

多图像支持：使用中的任何图像 images/ 目录
7强大的工具：列出、检索、检查、转换、调整大小和缩略图
高级加工：内置夏普，可实现高质量的图像处理
格式支持：JPG、PNG、WebP、GIF和BMP（只读）
多个传输：stdio用于本地测试，WebSocket/SSE用于远程部署
Smithery准备就绪：结构便于部署到Smithery
安全：内置路径遍历保护和输入验证

项目结构

image-mcp-test/
├── src/
│   └── index.ts          # Main MCP server with all tools
├── images/               # Directory containing images
│   └── test.jpg          # Sample image
├── dist/                 # Compiled JavaScript (after build)
├── package.json          # Project metadata and dependencies
├── tsconfig.json         # TypeScript configuration
└── README.md             # This file

安装

安装所需的依赖项：

npm install

局部测试

运行服务器

使用stdio传输在本地启动服务器：

npm start

对于自动重新加载的开发：

npm run dev

建筑

将TypeScript编译为JavaScript：

npm run build

编译后的输出将在 dist/ 目录。

使用Claude Desktop进行测试

要将此MCP服务器与Claude Desktop一起使用，请将其添加到您的Claude配置文件中：

视窗: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "image-server": {
      "command": "node",
      "args": ["path/to/image-mcp-test/dist/index.js"]
    }
  }
}

或者使用npx和tsx进行开发：

{
  "mcpServers": {
    "image-server": {
      "command": "npx",
      "args": ["tsx", "path/to/image-mcp-test/src/index.ts"]
    }
  }
}

添加配置后，重新启动Claude Desktop。

MCP检验员测试

这 MCP检查员是测试MCP服务器的好工具：

npx @modelcontextprotocol/inspector node dist/index.js

或用于开发：

npx @modelcontextprotocol/inspector npx tsx src/index.ts

这将打开一个web界面，您可以在其中：

查看所有可用工具
具有不同参数的测试工具调用
查看响应和调试问题

Smithery部署

此服务器已准备好部署到Smithery，这允许远程访问您的MCP服务器。

先决条件

安装Smithery CLI（如果尚未安装）：
```
npm install -g @smithery/cli
```
登录Smithery：
```
smithery login
```

部署

从项目根目录：

smithery deploy .

Smithery CLI将：

构建您的项目
打包服务器
将其部署到Smithery的基础设施中
为您提供访问MCP服务器的URL

使用已部署的服务器

部署后，您可以使用Smithery提供的URL连接到服务器。服务器将自动使用WebSocket/SSE传输进行远程连接。

可用工具

1.列表_图片

列出图像目录中所有可用的图像及其文件大小。

参数：无

退货：可用图像及其大小的文本列表

示例:

Available images:
- test.jpg (206.73 KB)
- example.png (45.23 KB)

2.获取图片

从images目录中按文件名返回特定图像。

参数:

filename （string，必填）：要检索的图像的文件名（例如“test.jpg”）

退货：具有适当MIME类型的MCP格式的图像内容

支持格式：JPG、JPEG、PNG、GIF、WebP、BMP

示例：请求“test.jpg”以接收base64编码数据形式的图像

3.获取图像元数据

返回有关图像的基本元数据，而不加载完整的图像数据。

参数:

filename （string，必填）：图像的文件名

退货：包含元数据的文本，包括：

文件名
格式
MIME类型
文件大小（字节、KB、MB）
创建日期
修改日期

示例:

Image Metadata:
- Filename: test.jpg
- Format: JPG
- MIME Type: image/jpeg
- Size: 206.73 KB (211695 bytes)
- Created: 2025-10-28T23:53:00.000Z
- Modified: 2025-10-28T23:53:00.000Z

4.获取图片信息

使用Sharp获取有关图像的详细技术信息。

参数:

filename （string，必填）：图像的文件名

退货：详细的技术信息包括：

尺寸（宽x高）
格式
通道数
色彩空间
位深度
阿尔法通道存在
DPI/密度
EXIF数据存在
ICC配置文件存在

示例:

Image Information:
- Filename: test.jpg
- Format: JPEG
- Dimensions: 1920 x 1080 pixels
- Channels: 3
- Color Space: srgb
- Bit Depth: uchar
- Has Alpha: No
- File Size: 206.73 KB
- Density: 72 DPI

5.转换图像

将图像从一种格式转换为另一种格式。

参数:

filename （string，必填）：源图像的文件名
targetFormat （枚举，必填）：目标格式-“jpg”、“jpeg”、“png”、“webp”、“gif”之一
quality （数字，可选）：有损格式的质量（1-100，默认值：90）

退货：以指定格式转换的图像

示例：将“test.jpg”转换为WebP格式，质量为85%

6.调整图像大小

将图像调整为指定尺寸。

参数:

filename （string，必填）：要调整大小的图像的文件名
width （数字，可选）：目标宽度（像素）
height （数字，可选）：目标高度（像素）
fit （枚举，可选）：如何适应图像-以下之一：
- contain （默认）：保留纵横比，包含在尺寸范围内
- cover：保持纵横比，覆盖两个维度
- fill：忽略纵横比，拉伸到精确尺寸
- inside：保留纵横比，调整大小使其尽可能大，同时确保尺寸小于或等于指定值
- outside：保留纵横比，调整大小以尽可能小，同时确保尺寸大于或等于指定值

退货：调整图像大小

备注：必须至少指定宽度或高度中的一个

示例：调整为800px宽度，保持纵横比

7.创建_缩略图

创建图像的缩略图版本。

参数:

filename （string，必填）：图像的文件名
maxDimension （数字，可选）：最大尺寸（像素）（默认值：200）

退货：缩略图图像

行为:

保持纵横比
符合最大尺寸x最大尺寸平方
不会放大小于maxDimension的图像

示例：创建150x150的“test.jpg”缩略图

运作原理

服务器初始化：FastMCP创建具有自动传输检测功能的MCP服务器
工具注册：所有7个工具都已注册其实现
图像处理：工具使用Node.js fs进行文件操作，使用Sharp进行高级处理
Base64编码：图像转换为base64，通过MCP传输
MCP响应：返回具有正确MIME类型的MCP格式的数据
运输搬运：FastMCP根据服务器的启动方式自动处理stdio、WebSocket或SSE

技术细节

框架：FastMCP（npm:FastMCP）
图像处理：夏普（npm:Sharp）
架构验证：Zod（npm:Zod）
语言：TypeScript
运行时：Node.js 18+
支持的读取格式：JPG、JPEG、PNG、GIF、WebP、BMP
支持的写入格式：JPG、PNG、webp、gif
编码：Base64
运输：stdio（本地）/Webocket或SSE（远程）

安全特性

路径横向保护：验证文件名以防止目录遍历攻击
格式验证：仅允许支持的图像格式
文件存在性检查：在操作之前验证文件是否存在
错误处理：带有描述性错误消息的全面try-catch块
输入验证：使用Zod模式进行类型安全参数验证

错误处理

服务器包括全面的错误处理：

读取前检查文件是否存在
所有操作的格式验证
路径遍历尝试的安全检查
尝试捕获所有文件和图像操作周围的块
返回给客户端的描述性错误消息
正确地将错误记录到stderr

添加自己的图像

只需将您的图像放在 images/ 目录：

# Copy images to the images directory
cp /path/to/your/image.jpg images/
cp /path/to/another/photo.png images/

服务器将自动检测并通过工具使其可用。

开发说明

所有MCP协议通信都通过stdout进行
服务器日志被写入stderr，以避免干扰协议
服务器使用ES模块（package.json中的类型：“模块”）
TypeScript配置了严格模式以确保类型安全
FastMCP自动处理MCP协议细节
夏普用于高质量、高性能的图像处理

依赖项

生产

fastmcp：MCP服务器框架
锋利：高性能图像处理库
黄道带：TypeScript第一模式验证

发展

打字稿：TypeScript编译器
多伦多证券交易所：用于开发的TypeScript执行引擎
@类型/节点：Node.js类型定义

业绩说明

夏普：使用libvips进行快速图像处理（比ImageMagick快得多）
流媒体：Sharp在可能的情况下使用流来提高内存效率
缓存：考虑对频繁请求的转换/缩略图实施缓存
大图像：Sharp可以有效地处理大图像，但处理非常大的图像可能需要时间

常见用例

图像检查：使用 list_images 和 get_image_info 探索可用图像
快速预览：使用 create_thumbnail 在加载完整图像之前进行小预览
格式转换：将图像转换为WebP以获得更好的压缩
响应图片：使用 resize_image 为各种屏幕尺寸创建不同尺寸
元数据抽取：使用 get_image_metadata 和 get_image_info 获取图像细节，但不加载完整图像

故障排除

问题：图像未显示在中 list_images

确保图像在 images/ 目录（不是项目根目录）
检查是否支持文件扩展名（jpg、jpeg、png、gif、webp、bmp）

问题：严重的安装错误

Sharp需要本地依赖
在Windows上，您可能需要Visual Studio生成工具
看清晰的安装文档

问题：服务器未启动

检查Node.js版本（需要18+）
跑 npm install 确保所有依赖项都已安装
检查 npm run build 无错误地完成

许可证

麻省理工学院

支持

对于以下问题：

FastMCP：参观 FastMCP存储库
夏普：参观清晰的文件
MCP协议：参观 MCP规范
史密瑟里：参观 Smithery文件

鸣谢

内置：

FastMCP 通过punkpeye
夏普作者：洛弗尔·富勒
模型上下文协议通过Anthropic