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:
```bash
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
```bash
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](https://bun.sh/).
Alternative: standalone binary
Download a pre-built binary from [Releases](https://github.com/pijusz/mcp-sanity-images/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:**
```bash
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)
```json
{
"mcpServers": {
"sanity-images": {
"command": "npx",
"args": ["-y", "mcp-sanity-images@latest"],
"env": {
"SANITY_PROJECT_ID": "your-project-id"
}
}
}
}
```
Using binary (macOS / Linux)
```json
{
"mcpServers": {
"sanity-images": {
"command": "/usr/local/bin/mcp-sanity-images",
"env": {
"SANITY_PROJECT_ID": "your-project-id"
}
}
}
}
```
Using binary (Windows)
```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.
```
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:
```bash
mcp-sanity-images --version
```
To update, download the new binary and replace the old one.
## Development
Requires [Bun](https://bun.sh/).
```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