mcp-sanity-images

MCP server for uploading local images to Sanity CMS.
Lets AI assistants upload files from your filesystem directly into Sanity as image assets.

Quick Start

1. Get your Sanity token

Either set the SANITY_TOKEN env var, or just log in with the Sanity CLI:

npx sanity login

The server reads the token from the Sanity CLI config automatically (~/.config/sanity/config.json on all platforms).

2. Add to Claude Code

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

That's it. Restart Claude Code and the tools are available. Every session runs the latest version automatically.

Also works with bunx mcp-sanity-images@latest if you have Bun.

Alternative: standalone binary

Download a pre-built binary from Releases:

Platform	File
macOS (Apple Silicon)	mcp-sanity-images-darwin-arm64
macOS (Intel)	mcp-sanity-images-darwin-x64
Linux	mcp-sanity-images-linux-x64
Windows	mcp-sanity-images-windows-x64.exe

macOS / Linux:

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

Windows (PowerShell):

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

Add to your claude_desktop_config.json:

Using npx (auto-updates)

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

Using binary (macOS / Linux)

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

Using binary (Windows)

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

Tools

Tool	Description
upload_image	Upload a single local image to Sanity as an asset
upload_and_set	Upload an image and patch it onto a document field
batch_upload	Upload all images from a folder as assets
list_images	List image files in a directory
groq_query	Run a GROQ query (find documents before attaching)

Supported formats: PNG, JPG/JPEG, WebP, GIF, SVG.

Configuration

Env var	Required	Default	Description
SANITY_PROJECT_ID	Yes	—	Your Sanity project ID
SANITY_DATASET	No	production	Dataset name
SANITY_TOKEN	No*	—	API token (*falls back to CLI auth)

All tools also accept projectId and dataset as parameters, overriding the env vars per-call.

Tool Details

upload_image

Upload a single file and get back the asset reference.

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

Returns { assetId, url, alt, reference } — the reference is ready to patch onto any Sanity image field.

upload_and_set

Upload + patch in one call.

filePath: "/path/to/hero.png"
documentId: "product-123"
fieldPath: "hero.image"

batch_upload

Upload all images from a directory.

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

list_images

List image files without uploading — useful for the AI to see what's available.

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

groq_query

Run any GROQ query. Useful to find document IDs before using upload_and_set.

query: "*[_type == 'product']{_id, title, slug}"

Updates

Using npx @latest (recommended): You always get the latest version — no manual updates needed.

Using a binary: The server checks for new releases on startup and logs to stderr if outdated:

[update] v0.2.0 available (current: v0.1.0). Download: https://github.com/pijusz/mcp-sanity-images/releases/latest

Check your installed version:

mcp-sanity-images --version

To update, download the new binary and replace the old one.

Development

Requires Bun.

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

License

MIT