Sanity MCP Server

# Sanity MCP Server <!-- omit in toc --> > 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](https://modelcontextprotocol.ai) 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 <!-- omit in toc --> - 🤖 **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 ## Table of Contents <!-- omit in toc --> - [🔌 Quickstart](#-quickstart) - [Remote server (preferred)](#remote-server-preferred) - [Local server prerequisites](#local-server-prerequisites) - [Add configuration for the Sanity MCP server](#add-configuration-for-the-sanity-mcp-server) - [🛠️ Available Tools](#️-available-tools) - [⚙️ Configuration](#️-configuration) - [🔑 API Tokens and Permissions](#-api-tokens-and-permissions) - [Generate API Tokens](#generate-api-tokens) - [Required Permissions](#required-permissions) - [Dataset Access](#dataset-access) - [Security Best Practices](#security-best-practices) - [👥 User Roles](#-user-roles) - [📦 Node.js Environment Setup](#-nodejs-environment-setup) - [🛠 Quick Setup for Node Version Manager Users](#-quick-setup-for-node-version-manager-users) - [🤔 Why is this needed?](#-why-is-this-needed) - [🔍 Troubleshooting](#-troubleshooting) - [💻 Development](#-development) - [Debugging](#debugging) ## 🔌 Quickstart ### Remote server (preferred) [](https://cursor.com/en/install-mcp?name=Sanity%20Developer&config=eyJ1cmwiOiJodHRwczovL21jcC5zYW5pdHkuaW8vZGV2ZWxvcGVyIiwidHlwZSI6Imh0dHAifQ%3D%3D) This README details how to run the MCP server locally. For a more production-ready setup, we recommend using the hosted remote server. ```json { "mcpServers": { "Sanity Developer": { "url": "https://mcp.sanity.io/developer", "type": "http" } } } ``` See [Sanity MCP Server](https://www.sanity.io/docs/compute-and-ai/mcp-server) in the documentation for install instructions in Claude Code, Cursor and more. ### Local server 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: ```bash cd /path/to/studio npm update sanity npx sanity schema deploy ``` When running in CI environments without Sanity login, you'll need to provide an auth token: ```bash SANITY_AUTH_TOKEN=<token> sanity schema deploy ``` > [!NOTE] > Schema deployment requires Sanity CLI version 3.88.1 or newer. 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. Here are some popular examples: - [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) - [Cursor IDE](https://docs.cursor.com/context/model-context-protocol) - [Visual Studio Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) - Custom MCP-compatible applications ### Add configuration for the Sanity MCP server To use the Sanity MCP server, add the following configuration to your application's MCP settings: ```json { "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" } } } } ``` For a complete list of all required and optional environment variables, see the [Configuration section](#️-configuration). The exact location of this configuration will depend on your application: | Application | Configuration Location | | -------------- | ------------------------------------------------- | | Claude Desktop | Claude Desktop configuration file | | Cursor | Workspace or global settings | | VS Code | Workspace or user settings (depends on extension) | | Custom Apps | Refer to your app's MCP integration docs | You don't get it to work? See the section on [Node.js configuration](#-nodejs-environment-setup). ## 🛠️ Available Tools ### Context & Setup <!-- omit in toc --> - **get_initial_context** – IMPORTANT: Must be called before using any other tools to initialize context and get usage instructions. - **get_sanity_config** – Retrieves current Sanity configuration (projectId, dataset, apiVersion, etc.) ### Document Operations <!-- omit in toc --> - **create_document** – Create a new document with AI-generated content based on instructions - **update_document** – Update an existing document with AI-generated content based on instructions - **patch_document** - Apply direct patch operations to modify specific parts of a document without using AI generation - **transform_document** – Transform document content while preserving formatting and structure, ideal for text replacements and style corrections - **translate_document** – Translate document content to another language while preserving formatting and structure - **query_documents** – Execute GROQ queries to search for and retrieve content - **publish_document** – Publish a draft document to make it live - **unpublish_document** – Unpublish a published document (moves it back to drafts) - **version_replace_document** – Replace the contents of a document version with contents from another document - **version_discard_document** –Discard a document version from a release (removes it from the release) - **version_unpublish_document** – Mark a document to be unpublished when the release is run - **delete_document** – Permanently delete a document and all its drafts ### Release Management <!-- omit in toc --> - **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 - **publish_release** – Publish a release immediately - **archive_release** – Archive a release that is no longer active - **unarchive_release** – Restore an archived release - **unschedule_release** – Remove a previously set schedule from a release - **delete_release** – Delete a release ### Version Management <!-- omit in toc --> - **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 <!-- omit in toc --> - **list_datasets** – List all datasets in the project - **create_dataset** – Create a new dataset - **update_dataset** – Modify dataset settings ### Schema Information <!-- omit in toc --> - **get_schema** – Get schema details, either full schema or for a specific type - **list_workspace_schemas** – Get a list of all available workspace schema names ### GROQ Support <!-- omit in toc --> - **get_groq_specification** – Get the GROQ language specification summary ### Embeddings & Semantic Search <!-- omit in toc --> - **list_embeddings_indices** – List all available embeddings indices - **semantic_search** – Perform semantic search on an embeddings index ### Project Information <!-- omit in toc --> - **list_projects** – List all Sanity projects associated with your account - **get_project_studios** – Get studio applications linked to a specific project ## ⚙️ Configuration The server takes the following environment variables: | 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). Adjust based on your model's context limits. Higher limits may pollute the conversation context with excessive data | ❌ | > [!WARNING] > **Using AI with Production Datasets** > When configuring the MCP server with a token that has write access to a production dataset, please be aware that the AI can perform destructive actions like creating, updating, or deleting content. This is not a concern if you're using a read-only token. While we are actively developing guardrails, you should exercise caution and consider using a development/staging dataset for testing AI operations that require write access. ### 🔑 API Tokens and Permissions The MCP server requires appropriate API tokens and permissions to function correctly. Here's what you need to know: #### Generate API Tokens From the terminal: ```bash npx sanity tokens add "MCP Server" --role <role> ``` Or from Manage: - Run `npx sanity manage` from your Studio root - In your project's management console: Settings > API > Tokens - Click "Add new token" - Create a dedicated token for your MCP server usage (e.g. `mcp-server`) - Store the token securely - it's only shown once! #### Required Permissions The token needs appropriate permissions based on your usage - **For read operations:** `viewer` role is sufficient - **For mutations:** `editor` or `developer` role recommended - **For project changes** (like managing datasets): `administrator` role may be needed #### Dataset Access - **Public datasets:** Content is readable by unauthenticated users - **Private datasets:** Require proper token authentication - **Draft and versioned content:** Only accessible to authenticated users with appropriate permissions #### Security Best Practices - Use separate tokens for different environments (development, staging, production) - Never commit tokens to version control - Consider using environment variables for token management - Regularly rotate tokens for security ### 👥 User Roles The server supports two user roles: - **developer**: Access to all tools - **editor**: Content-focused tools without project administration ## 📦 Node.js Environment Setup > [!IMPORTANT] > **For Node Version Manager Users** > If you use `nvm`, `mise`, `fnm`, `nvm-windows` or similar tools, you'll need to follow the setup steps below to ensure MCP servers can access Node.js. This is a one-time setup that will save you troubleshooting time later. This is [an ongoing issue](https://github.com/modelcontextprotocol/servers/issues/64) with MCP servers. ### 🛠 Quick Setup for Node Version Manager Users 1. First, activate your preferred Node.js version: ```bash # 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 (choose your OS): **On macOS/Linux:** ```bash sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx ``` > [!NOTE] > While using `sudo` generally requires caution, it's safe in this context because: > > - We're only creating symlinks to your existing Node.js binaries > - The target directory (`/usr/local/bin`) is a standard system location for user-installed programs > - The symlinks only point to binaries you've already installed and trust > - You can easily remove these symlinks later with `sudo rm` **On Windows (PowerShell as Administrator):** ```powershell 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: ```bash # Should show your chosen Node version /usr/local/bin/node --version # macOS/Linux "C:\Program Files\nodejs\node.exe" --version # Windows ``` ### 🤔 Why is this needed? MCP servers are launched by calling `node` and `npx` binaries directly. When using Node version managers, these binaries are managed in isolated environments that aren't automatically accessible to system applications. The symlinks above create a bridge between your version manager and the system paths that MCP servers use. ### 🔍 Troubleshooting If you switch Node versions often: - Remember to update your symlinks when changing Node versions - You can create a shell alias or script to automate this: ```bash # Example alias for your .bashrc or .zshrc alias update-node-symlinks='sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx' ``` To remove the symlinks later: ```bash # macOS/Linux sudo rm /usr/local/bin/node /usr/local/bin/npx # Windows (PowerShell as Admin) Remove-Item "C:\Program Files\nodejs\node.exe", "C:\Program Files\nodejs\npx.cmd" ``` ## 💻 Development Install dependencies: ```bash pnpm install ``` Build and run in development mode: ```bash pnpm run dev ``` Build the server: ```bash pnpm run build ``` Run the built server: ```bash pnpm start ``` ### Debugging For debugging, you can use the MCP inspector: ```bash npx @modelcontextprotocol/inspector \ -e SANITY_API_TOKEN=<token> \ -e SANITY_PROJECT_ID=<project_id> \ -e SANITY_API_HOST=https://api.sanity.io \ -e SANITY_DATASET=<ds> \ -e MCP_USER_ROLE=developer \ node build/index.js ``` This will provide a web interface for inspecting and testing the available tools.