Mcp Sanity Images

io.github.pijuszPublished by GitHub account pijuszv0.3.7Updated Nov 3, 2026

MCP server for uploading local images to Sanity CMS

VerifiedSTDIODesktop onlyFiles & StorageMedia & Design

Overview

AI-generated overview

Local MCP server that lets an assistant upload local image files into Sanity CMS as assets and attach them to documents.

What you can do
  • Upload a single local image to Sanity and get back an asset reference
  • Upload an image and patch it onto a document field in one call
  • Batch-upload every image in a folder, with failures listed separately
  • List image files in a directory without uploading
  • Run read-only GROQ queries to find document IDs before attaching images
When to use it
Useful when you keep images on disk and want an assistant to push them into a Sanity dataset and wire them into content fields, for example filling in product or article images without opening Sanity Studio.
Requirements
Runs locally over stdio via npx, bunx or a prebuilt binary (macOS, Linux, Windows). Needs SANITY_PROJECT_ID; SANITY_DATASET defaults to production. A Sanity API token is read from SANITY_TOKEN or from the Sanity CLI login config. Network access to Sanity is required.
Before you install
The token grants write access to the Sanity project, so treat it as a secret. Uploads and document patches change live content; upload_and_set can patch published documents and may leave drafts out of sync. Batch uploads send every image in a chosen folder to Sanity. The npx @latest setup always pulls the newest version.

Installation

In SourceWeft

  1. Open Mcp Sanity Images in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[MCPi 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:

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.

Alternative: standalone binary

Download a pre-built binary from Releases:

PlatformFile
macOS (Apple Silicon)mcp-sanity-images-darwin-arm64
macOS (Intel)mcp-sanity-images-darwin-x64
Linuxmcp-sanity-images-linux-x64
Windowsmcp-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-arm64chmod +x mcp-sanity-imagessudo 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

ToolDescription
upload_imageUpload a single local image to Sanity as an asset
upload_and_setUpload an image and patch it onto a document field
batch_uploadUpload all images from a folder as assets
list_imagesList image files in a directory
groq_queryRun a GROQ query (find documents before attaching); optional perspective (raw default, published, drafts)

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

Configuration

Env varRequiredDefaultDescription
SANITY_PROJECT_IDYes—Your Sanity project ID
SANITY_DATASETNoproductionDataset name
SANITY_TOKENNo*—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"      # or "drafts.product-123" to patch the draftfieldPath: "hero.image"

Before uploading, the tool checks which of <id> and drafts.<id> exist, so a wrong ID uploads nothing:

You passExistsPatched
product-123published onlyproduct-123
product-123published + draftproduct-123, with a note that the draft was left alone (Studio shows the draft, and publishing it overwrites the field)
product-123draft only (never published)drafts.product-123, with a note and requestedDocumentId
drafts.product-123draftdrafts.product-123
anythingneithernothing; returns "Document not found"

The response's documentId is the document actually patched. Mutations are sent with returnIds=true&visibility=sync, so a follow-up groq_query sees the change.

batch_upload

Upload all images from a directory.

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

Returns { uploaded, assets }. If some files fail, the rest still upload and the failures are listed in failed (with failedCount).

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 (read-only). Long queries are sent via POST automatically. Useful to find document IDs before using upload_and_set.

query: "*[_type == 'product']{_id, title, slug}"perspective: "raw"   # optional: raw (default) | published | drafts
PerspectiveWhat the query sees
raw (default)Published documents and drafts side by side, with their real IDs (drafts.-prefixed for drafts). Pass these IDs straight to upload_and_set.
publishedPublished documents only; drafts are invisible.
draftsEvery draft applied as if published. _id is always the published ID (even for never-published drafts); the stored ID is in _originalId.

The server pins Sanity API version v2025-02-19. That version made published the API's default perspective. This tool sends raw unless you ask otherwise, so results match what earlier releases (API v2021-10-21, default raw) returned.

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:

[mcp-sanity-images] WARN v0.5.0 available (current: v0.4.1). 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.gitcd mcp-sanity-imagesbun installbun testbun run lint      # biome checkbun run build     # compile standalone binary

License

MIT

Source: README.md at commit 835c357

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.7LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts