Sanity CMS MCP server

The Sanity MCP Server enables AI-powered content operations for Sanity by implementing the Model Context Protocol. This server connects your Sanity projects with AI tools like Claude, Cursor, and VS Code, allowing AI models to understand your content structure and perform operations through natural language instructions.

Installation

Prerequisites

Before using the MCP server, you need to:

1. Deploy your Sanity Studio with schema manifest

   # Option A: If you have the CLI installed globally
   npm install -g sanity
   cd /path/to/studio
   sanity schema deploy
   
   # Option B: Update your Studio
   cd /path/to/studio
   npm update sanity
   npx sanity schema deploy
   

   For CI environments without Sanity login:

   SANITY_AUTH_TOKEN=<token> sanity schema deploy
   

2. Gather your API credentials

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

Configure 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",
        "MCP_USER_ROLE": "developer"
      }
    }
  }
}

The configuration location depends on your application (Claude Desktop, Cursor, VS Code, etc.).

Node.js Environment Setup

Setup for Node Version Manager Users

1. Activate your preferred Node.js version:

   # Using nvm
   nvm use 20   # or your preferred version
   
   # Using mise
   mise use node@20
   
   # Using fnm
   fnm use 20
   

2. Create the necessary symlinks:

   On macOS/Linux:

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

   On 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 the setup:

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

Configuration Options

Variable	Description	Required
SANITY_API_TOKEN	Your Sanity API token	✅
SANITY_PROJECT_ID	Your Sanity project ID	✅
SANITY_DATASET	The dataset to use	✅
MCP_USER_ROLE	Determines tool access level (developer or editor)	✅
SANITY_API_HOST	API host (defaults to https://api.sanity.io)	❌
MAX_TOOL_TOKEN_OUTPUT	Maximum token output for tool responses (defaults to 50000)	❌

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

2. Required Permissions:

   • For basic read operations: viewer role
   • For content management: editor or developer role
   • For advanced operations: administrator role may be needed

User Roles

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

Available Tools

Context & Setup

• get_initial_context – Initialize context and get usage instructions
• get_sanity_config – Retrieve current Sanity configuration

Document Operations

• create_document – Create a new document with AI-generated content
• update_document – Update an existing document with AI-generated content
• patch_document - Apply direct patch operations to modify specific parts of a document
• transform_document – Transform document content while preserving formatting and structure
• translate_document – Translate document content to another language
• query_documents – Execute GROQ queries to search for and retrieve content
• publish_document – Publish a draft document
• unpublish_document – Unpublish a published document
• delete_document – Permanently delete a document and all its drafts

Release Management

• list_releases – List content releases
• 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
• publish_release – Publish a release immediately
• archive_release – Archive a release
• unarchive_release – Restore an archived release
• unschedule_release – Remove a previously set schedule from a release
• delete_release – Delete a release

Other Tool Categories

• Version Management
• Dataset Management
• Schema Information
• GROQ Support
• Embeddings & Semantic Search
• Project Information

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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","MCP_USER_ROLE":"developer"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "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",
                "MCP_USER_ROLE": "developer"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "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",
                "MCP_USER_ROLE": "developer"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect