MCP HubMCP Hub
sanity-io

sanity-mcp-server

by: sanity-io

Sanity MCP Server

34created 05/03/2025
Visit
Sanity

📌Overview

Purpose: The main goal of the Sanity MCP server is to facilitate the integration and management of Sanity's content for applications using the Claude Desktop environment.

Overview: The Sanity MCP server provides a streamlined way to connect and manage content workflows between Sanity’s backend and client applications, with easy setup and configuration for developers.

Key Features:

  • Seamless Integration: Allows easy connection of the Claude Desktop application to the Sanity MCP server, streamlining content management.

  • Environment Configuration: Supports configuration through JSON, enabling developers to set up necessary environment variables for secure and customized server interactions.

Sanity MCP Server

Transform your content operations with AI-powered tools for Sanity. Create, manage, and explore your content through natural language conversations in your favorite AI-enabled editor.

Sanity MCP Server implements the Model Context Protocol to connect your Sanity projects with AI tools like Claude, Cursor, and VS Code. It enables AI models to understand your content structure and perform operations through natural language instructions.

✨ Key Features

  • 🤖 Content Intelligence: Let AI explore and understand your content library
  • 🔄 Content Operations: Automate tasks through natural language instructions
  • 📊 Schema-Aware: AI respects your content structure and validation rules
  • 🚀 Release Management: Plan and organize content releases effortlessly
  • 🔍 Semantic Search: Find content based on meaning, not just keywords

Quickstart

Prerequisites

Before you can use the MCP server, you need to:

  1. Deploy your Sanity Studio with schema manifest

    The MCP server needs access to your content structure to work effectively. Deploy your schema manifest using one of these approaches:

    # Option A: Force latest CLI version (recommended)
cd /path/to/studio
SANITY_CLI_SCHEMA_STORE_ENABLED=true npx --ignore-existing sanity@latest schema deploy

# Option B: If you have the CLI installed globally
npm install -g sanity
cd /path/to/studio
SANITY_CLI_SCHEMA_STORE_ENABLED=true sanity schema deploy

# Option C: Update your Studio first
cd /path/to/studio
npm update sanity
SANITY_CLI_SCHEMA_STORE_ENABLED=true npx sanity schema deploy

    Schema deployment requires both the latest CLI version and the SANITY_CLI_SCHEMA_STORE_ENABLED flag. This feature will be enabled by default in a future release.

  2. Get your API credentials

    • Project ID
    • Dataset name
    • API token with appropriate permissions

This MCP server can be used with any application that supports the Model Context Protocol. Popular examples include:

  • Claude Desktop
  • Cursor IDE
  • Visual Studio Code
  • Custom MCP-compatible applications

Add configuration for the Sanity MCP server

Add the following configuration to your application's MCP settings:

{
  "mcpServers": {
    "sanity": {
      "command": "npx",
      "args": ["-y", "@sanity/mcp-server@latest"],
      "env": {
        "SANITY_PROJECT_ID": "your-project-id",
        "SANITY_DATASET": "production",
        "SANITY_API_TOKEN": "your-sanity-api-token"
      }
    }
  }
}

The configuration location depends on your application:

ApplicationConfiguration Location
Claude DesktopClaude Desktop configuration file
CursorWorkspace or global settings
VS CodeWorkspace or user settings (depends on extension)
Custom AppsRefer to your app's MCP integration docs

If you have issues, see the Node.js Environment Setup.

🛠️ Available Tools

Context & Setup

  • get_initial_context – Must be called before using other tools to initialize context and get usage instructions.
  • get_sanity_config – Retrieves current Sanity configuration (projectId, dataset, apiVersion, etc.)

Document Operations

  • create_document – Create a new document with AI-generated content based on instructions
  • update_document – Update an existing document with AI-generated content
  • patch_document - Apply direct patch operations to modify parts of a document
  • query_documents – Execute GROQ queries to search for and retrieve content
  • document_action – Perform actions like publishing, unpublishing, or deleting documents

Release Management

  • list_releases – List content releases, optionally filtered by state
  • create_release – Create a new content release
  • edit_release – Update metadata for an existing release
  • schedule_release – Schedule a release to publish at a specific time
  • release_action – Perform actions on releases (publish, archive, unarchive, unschedule, delete)

Version Management

  • create_version – Create a version of a document for a specific release
  • discard_version – Delete a specific version document from a release
  • mark_for_unpublish – Mark a document to be unpublished when a specific release is published

Dataset Management

  • get_datasets – List all datasets in the project
  • create_dataset – Create a new dataset
  • update_dataset – Modify dataset settings

Schema Information

  • get_schema – Get schema details, either full schema or for a specific type
  • list_schema_ids – List all available schema IDs

GROQ Support

  • get_groq_specification – Get the GROQ language specification summary

Embeddings & Semantic Search

  • list_embeddings_indices – List all available embeddings indices
  • semantic_search – Perform semantic search on an embeddings index

Project Information

  • list_projects – List all Sanity projects associated with your account
  • get_project_studios – Get studio applications linked to a specific project

⚙️ Configuration

The server accepts the following environment variables:

VariableDescriptionRequired
SANITY_API_TOKENYour Sanity API token✅
SANITY_PROJECT_IDYour Sanity project ID✅
SANITY_DATASETThe dataset to use✅
SANITY_API_HOSTAPI host (defaults to https://api.sanity.io)❌
MCP_USER_ROLEDetermines tool access level (developer or editor)❌

Using AI with Production Datasets
When configuring the MCP server with a token that has write access to a production dataset, be cautious as AI can perform destructive actions (create, update, delete content). Consider using a read-only token or a development/staging dataset for testing.

🔑 API Tokens and Permissions

  1. Generate a Robot Token:

    • Go to your project's management console: Settings > API > Tokens
    • Click "Add new token"
    • Create a dedicated token for your MCP server usage
    • Store the token securely - shown only once!

  2. Required Permissions:

    • For basic read operations: viewer role is sufficient
    • For content management: editor or developer role recommended
    • For advanced operations (like managing datasets): administrator role may be needed

  3. Dataset Access:

    • Public datasets: readable by unauthenticated users
    • Private datasets: require token authentication
    • Draft and versioned content: only accessible with appropriate permissions

  4. Security Best Practices:

    • Use separate tokens for different environments
    • Never commit tokens to version control
    • Use environment variables for token management
    • Regularly rotate tokens for security

👥 User Roles

  • developer: Access to all tools
  • editor: Content-focused tools without project administration

📦 Node.js Environment Setup

For Node Version Manager Users (nvm, mise, fnm, nvm-windows, etc.), follow these steps to allow MCP servers to access Node.js binaries. This is a one-time setup to avoid troubleshooting later.

🛠 Quick Setup for Node Version Manager Users

  1. Activate your preferred Node.js version:

    # Using nvm
nvm use 20

# Using mise
mise use node@20

# Using fnm
fnm use 20

  2. Create necessary symlinks for your OS:

    macOS/Linux:

    sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx

    Creating symlinks to your existing Node.js binaries is safe and can be removed later with sudo rm.

    Windows (PowerShell as Administrator):

    New-Item -ItemType SymbolicLink -Path "C:\Program Files\nodejs\node.exe" -Target (Get-Command node).Source -Force
New-Item -ItemType SymbolicLink -Path "C:\Program Files\nodejs\npx.cmd" -Target (Get-Command npx).Source -Force

  3. Verify setup:

    /usr/local/bin/node --version  # macOS/Linux
"C:\Program Files\nodejs\node.exe" --version  # Windows

🤔 Why Is This Needed?

MCP servers launch node and npx binaries directly. Node version managers keep these binaries in isolated environments inaccessible to system applications. The symlinks bridge your version manager with system paths used by MCP servers.

🔍 Troubleshooting

  • Update symlinks when switching Node versions.

  • Automate symlink update with a shell alias:

    alias update-node-symlinks='sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx'

  • To remove symlinks later:

    sudo rm /usr/local/bin/node /usr/local/bin/npx

    On Windows (PowerShell as Admin):

    Remove-Item "C:\Program Files\nodejs\node.exe", "C:\Program Files\nodejs\npx.cmd"

💻 Development

Install dependencies:

pnpm install

Build and run in development mode:

pnpm run dev

Build the server:

pnpm run build

Run the built server:

pnpm start

Debugging

Use the MCP inspector:

npx @modelcontextprotocol/inspector -e SANITY_API_TOKEN=<token> -e SANITY_PROJECT_ID=<project_id> -e SANITY_DATASET=<ds> -e MCP_USER_ROLE=developer node path/to/build/index.js

This provides a web interface to inspect and test available tools.