MCP 集成

PicFast 内置 Model Context Protocol（MCP）服务器，让 Claude、Cursor、VS Code Copilot 等 AI Agent 直接与你的图床平台交互。AI 助手可通过标准化协议完成图片上传、浏览与管理。

什么是 MCP？

Model Context Protocol 是一项开放标准，用于让 AI 应用与外部工具和数据源交互。PicFast 的 MCP 服务器将你的图床以工具和资源的形式暴露给任意兼容 MCP 的客户端。

安装

MCP 服务器以 @picfast/mcp 发布在 npm。无需全局安装，通过 npx 直接运行：

npx @picfast/mcp

配置

在 MCP 客户端设置中配置以下环境变量：

变量	必填	说明
`PICFAST_BASE_URL`	是	PicFast 服务器地址，如 `https://picfast.example.com`
`PICFAST_API_TOKEN`	否	用于认证操作的 API token。在 PicFast 管理后台创建（token 以 `img_` 为前缀）。不填则仅支持游客上传。

Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "picfast": {
      "command": "npx",
      "args": ["-y", "@picfast/mcp"],
      "env": {
        "PICFAST_BASE_URL": "https://picfast.example.com",
        "PICFAST_API_TOKEN": "img_xxxxxxxx"
      }
    }
  }
}

Cursor / VS Code

配置格式同上，在 设置 → MCP 中添加。

工具

工具	认证	说明
`upload_image`	否	从本地文件路径上传图片。无需 token 即可在游客模式下使用。
`list_images`	是	分页查看已上传的图片列表。
`get_image`	是	获取图片详情及所有分享链接格式（URL、Markdown、HTML、BBCode）。
`delete_image`	是	按 key 删除指定图片。
`get_usage_stats`	是	查看当前存储配额、使用量及图片数量。

上传响应格式

upload_image 调用成功后返回的 JSON 字段：

{
  "key": "abc123",
  "url": "https://picfast.example.com/i/abc123.png",
  "markdown": "![](https://picfast.example.com/i/abc123.png)",
  "html": "<img src=\"https://picfast.example.com/i/abc123.png\" />",
  "bbcode": "[img]https://picfast.example.com/i/abc123.png[/img]",
  "mimetype": "image/png",
  "original_size": 204800,
  "stored_size": 196500,
  "processed": true
}

资源

MCP 客户端还可以读取以下资源 URI 获取结构化数据：

URI	认证	说明
`picfast://user/profile`	是	当前用户信息
`picfast://images/{key}`	是	指定图片的元数据与链接

游客模式

未设置 PICFAST_API_TOKEN 时，MCP 服务器以游客模式运行，仅 upload_image 可用。需在 PicFast 管理后台启用游客上传功能（站点设置 → 允许游客上传）。其他需认证的工具在无 token 调用时将返回错误。

错误处理

所有工具调用失败时返回统一的 JSON 结构：

{"error": {"code": "UPLOAD_FAILED", "message": "上传未能完成。"}}

错误码包含：UNAUTHORIZED、FORBIDDEN_SCOPE、INVALID_IMAGE_DATA、UPLOAD_FAILED、IMAGE_NOT_FOUND、INTERNAL_ERROR。

许可证

MCP 服务器采用 MIT 许可证。npm 包地址：@picfast/mcp。