mcp-sanity-images

用于将本地图片上传到 Sanity CMS 的 MCP 服务。
让 AI 助手能够直接将文件系统中的文件上传到 Sanity，作为图片资源。

快速开始

1. 获取 Sanity 令牌

设置 SANITY_TOKEN 环境变量，或直接使用 Sanity CLI 登录：

npx sanity login

服务会自动从 Sanity CLI 配置中读取令牌（所有平台上均为 ~/.config/sanity/config.json）。

2. 添加到 Claude Code

claude mcp add sanity-images --scope user --transport stdio \
  -e SANITY_PROJECT_ID=your-project-id \
  -- npx -y mcp-sanity-images@latest

就这么简单。重启 Claude Code 后即可使用这些工具。每次会话都会自动运行最新版本。

如果你安装了 Bun，也可以使用 bunx mcp-sanity-images@latest。

curl -Lo mcp-sanity-images https://github.com/pijusz/mcp-sanity-images/releases/latest/download/mcp-sanity-images-darwin-arm64
chmod +x mcp-sanity-images
sudo mv mcp-sanity-images /usr/local/bin/
claude mcp add sanity-images --scope user --transport stdio \
  -e SANITY_PROJECT_ID=your-project-id \
  -- /usr/local/bin/mcp-sanity-images

Invoke-WebRequest -Uri "https://github.com/pijusz/mcp-sanity-images/releases/latest/download/mcp-sanity-images-windows-x64.exe" -OutFile "$env:LOCALAPPDATA\mcp-sanity-images.exe"
claude mcp add sanity-images --scope user --transport stdio -e SANITY_PROJECT_ID=your-project-id -- "%LOCALAPPDATA%\mcp-sanity-images.exe"

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "sanity-images": {
      "command": "npx",
      "args": ["-y", "mcp-sanity-images@latest"],
      "env": {
        "SANITY_PROJECT_ID": "your-project-id"
      }
    }
  }
}

{
  "mcpServers": {
    "sanity-images": {
      "command": "/usr/local/bin/mcp-sanity-images",
      "env": {
        "SANITY_PROJECT_ID": "your-project-id"
      }
    }
  }
}

{
  "mcpServers": {
    "sanity-images": {
      "command": "%LOCALAPPDATA%\\mcp-sanity-images.exe",
      "env": {
        "SANITY_PROJECT_ID": "your-project-id"
      }
    }
  }
}

工具

支持的格式：PNG、JPG/JPEG、WebP、GIF、SVG。

配置

所有工具也接受 projectId 和 dataset 参数，可在每次调用时覆盖环境变量。

工具详情

upload_image

上传单个文件并返回资源引用。

filePath: "/path/to/hero.png"
alt: "Hero banner"  (optional — derived from filename)

返回 { assetId, url, alt, reference }——reference 可直接用于设置任何 Sanity 图片字段。

upload_and_set

一次调用即可完成上传和设置。

filePath: "/path/to/hero.png"
documentId: "product-123"      # or "drafts.product-123" to patch the draft
fieldPath: "hero.image"

上传前，工具会检查 <id> 和 drafts.<id> 中哪些文档存在，因此 ID 错误时不会上传任何内容：

响应中的 documentId 是实际被设置的文档。变更会以 returnIds=true&visibility=sync 发送，因此后续的 groq_query 可以看到变更。

batch_upload

上传目录中的所有图片。

directory: "/path/to/images"
recursive: true

返回 { uploaded, assets }。如果部分文件上传失败，其余文件仍会继续上传，失败项会列在 failed 中（并附带 failedCount）。

list_images

列出图片文件但不上传——方便 AI 查看有哪些可用图片。

directory: "/path/to/images"
recursive: true

groq_query

运行任意 GROQ 查询（只读）。较长的查询会自动通过 POST 发送。可用于查找文档 ID，以便随后使用 upload_and_set。

query: "*[_type == 'product']{_id, title, slug}"
perspective: "raw"   # optional: raw (default) | published | drafts

服务器固定使用 Sanity API 版本 v2025-02-19。该版本将 published 设为 API 的默认 perspective。此工具会发送 raw，除非你另有要求，因此结果与早期版本（API v2021-10-21，默认值为 raw）返回的结果一致。

更新

使用 npx @latest（推荐）：始终获取最新版本，无需手动更新。

使用二进制文件：服务器会在启动时检查是否有新版本，并在版本过旧时向 stderr 输出日志：

[mcp-sanity-images] WARN v0.5.0 available (current: v0.4.1). Download: https://github.com/pijusz/mcp-sanity-images/releases/latest

检查已安装的版本：

mcp-sanity-images --version

要更新，请下载新的二进制文件并替换旧文件。

开发

需要 Bun。

git clone https://github.com/pijusz/mcp-sanity-images.git
cd mcp-sanity-images
bun install
bun test
bun run lint      # biome check
bun run build     # compile standalone binary

许可证

MIT