Sanity CMS MCP server

The Sanity MCP Server implements the Model Context Protocol to connect your Sanity projects with AI tools, enabling natural language interactions with your content. It allows AI models to understand your content structure and perform operations through conversational 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. Get your API credentials

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

Adding the Sanity MCP Server Configuration

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 location for this configuration depends on your application:

Node.js Environment Setup

Quick Setup for Node Version Manager Users

1. First, 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. Then, 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

The server uses the following environment variables:

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 is sufficient
   • For content management: editor or developer role recommended
   • For advanced operations: administrator role may be needed

User Roles

The server supports two user roles:

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

Available Tools

Once you've set up the Sanity MCP server, you'll have access to various tools for different operations:

Context & Setup

• get_initial_context – Must be called first to initialize context
• get_sanity_config – Retrieves 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
• translate_document – Translate document content to another language
• query_documents – Execute GROQ queries to search for content
• document_action – Perform actions like publishing, unpublishing, or deleting documents

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
• release_action – Perform actions on releases

Version Management

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

Other Tools

• Tools for dataset management, schema information, GROQ support, embeddings & semantic search, and project information are also available

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.