MCP Sanity Images README

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:

Terminal

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

Terminal

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:

Terminal

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):

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)

config.json

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

Using binary (macOS / Linux)

config.json

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

Using binary (Windows)

config.json

{
  "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.

Code

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.

Code

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

batch_upload

Upload all images from a directory.

Code

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

list_images

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

Code

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

groq_query

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

Code

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:

Code

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

Check your installed version:

bash

mcp-sanity-images --version

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

Development

Requires Bun.

bash

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