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.

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:

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

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