npm package: @iflow-mcp/sanity-mcp-server
Description: > [!NOTE] > **This repository is archived and no longer actively maintained.** > We now recommend using our hosted server at **[mcp.sanity.io](https://mcp.sanity.io)** which offers streamable HTTP transport, OAuth authentication, continually updated tools
Latest version: 0.12.1

# Sanity MCP Server <!-- omit in toc -->

> [!NOTE]
> **This repository is archived and no longer actively maintained.**
> We now recommend using our hosted server at **[mcp.sanity.io](https://mcp.sanity.io)** which offers streamable HTTP transport, OAuth authentication, continually updated tools, and production-ready reliability without any local setup required.

> 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)

The hosted server at **[mcp.sanity.io](https://mcp.sanity.io)** supports modern streamable HTTP transport and OAuth authentication. Add this configuration to your MCP client:

```json
{
  "mcpServers": {
    "Sanity": {
      "url": "https://mcp.sanity.io",
      "type": "http"
    }
  }
}
```

**Benefits of the remote server:**
- Streamable HTTP for better performance
- OAuth for secure authentication (no tokens to manage)
- Latest tools and features automatically
- No Node.js setup required

See [mcp.sanity.io](https://mcp.sanity.io) for complete installation instructions for Claude Code, Cursor, and other MCP clients.

---

**Note:** The local server instructions below are for self-hosting only. This repository is archived and no longer maintained.

### 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.