{"id":28768839,"url":"https://github.com/sanity-io/sanity-mcp-server","last_synced_at":"2025-10-12T11:54:02.640Z","repository":{"id":282392641,"uuid":"943133330","full_name":"sanity-io/sanity-mcp-server","owner":"sanity-io","description":"Connect your Sanity content to AI agents. Create, update, and explore structured content using Claude, Cursor, and VS Code via the Model Context Protocol. Transform content operations from complex queries to simple conversations—giving your team superpowers without sacrificing structure.","archived":false,"fork":false,"pushed_at":"2025-06-13T14:04:04.000Z","size":1626,"stargazers_count":59,"open_issues_count":4,"forks_count":15,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-06-13T14:07:54.204Z","etag":null,"topics":["cms","mcp","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sanity-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-05T08:13:54.000Z","updated_at":"2025-06-13T14:04:08.000Z","dependencies_parsed_at":"2025-06-02T14:55:12.447Z","dependency_job_id":null,"html_url":"https://github.com/sanity-io/sanity-mcp-server","commit_stats":null,"previous_names":["sanity-io/sanity-mcp-server"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/sanity-io/sanity-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanity-io%2Fsanity-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanity-io%2Fsanity-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanity-io%2Fsanity-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanity-io%2Fsanity-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sanity-io","download_url":"https://codeload.github.com/sanity-io/sanity-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanity-io%2Fsanity-mcp-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260364947,"owners_count":22998028,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cms","mcp","mcp-server"],"created_at":"2025-06-17T13:03:28.022Z","updated_at":"2025-10-12T11:54:02.635Z","avatar_url":"https://github.com/sanity-io.png","language":"TypeScript","funding_links":[],"categories":["Content Creation","Other Tools and Integrations","Headless CMS","Content Management"],"sub_categories":["How to Submit"],"readme":"# Sanity MCP Server \u003c!-- omit in toc --\u003e\n\n\u003e 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.\n\nSanity 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.\n\n## ✨ Key Features \u003c!-- omit in toc --\u003e\n\n- 🤖 **Content Intelligence**: Let AI explore and understand your content library\n- 🔄 **Content Operations**: Automate tasks through natural language instructions\n- 📊 **Schema-Aware**: AI respects your content structure and validation rules\n- 🚀 **Release Management**: Plan and organize content releases effortlessly\n- 🔍 **Semantic Search**: Find content based on meaning, not just keywords\n\n## Table of Contents \u003c!-- omit in toc --\u003e\n\n- [🔌 Quickstart](#-quickstart)\n  - [Remote server (preferred)](#remote-server-preferred)\n  - [Local server prerequisites](#local-server-prerequisites)\n  - [Add configuration for the Sanity MCP server](#add-configuration-for-the-sanity-mcp-server)\n- [🛠️ Available Tools](#️-available-tools)\n- [⚙️ Configuration](#️-configuration)\n  - [🔑 API Tokens and Permissions](#-api-tokens-and-permissions)\n    - [Generate API Tokens](#generate-api-tokens)\n    - [Required Permissions](#required-permissions)\n    - [Dataset Access](#dataset-access)\n    - [Security Best Practices](#security-best-practices)\n  - [👥 User Roles](#-user-roles)\n- [📦 Node.js Environment Setup](#-nodejs-environment-setup)\n  - [🛠 Quick Setup for Node Version Manager Users](#-quick-setup-for-node-version-manager-users)\n  - [🤔 Why is this needed?](#-why-is-this-needed)\n  - [🔍 Troubleshooting](#-troubleshooting)\n- [💻 Development](#-development)\n  - [Debugging](#debugging)\n\n## 🔌 Quickstart\n\n### Remote server (preferred)\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=Sanity%20Developer\u0026config=eyJ1cmwiOiJodHRwczovL21jcC5zYW5pdHkuaW8vZGV2ZWxvcGVyIiwidHlwZSI6Imh0dHAifQ%3D%3D)\n\nThis README details how to run the MCP server locally. For a more production-ready setup, we recommend using the hosted remote server.\n\n```json\n{\n  \"mcpServers\": {\n    \"Sanity Developer\": {\n      \"url\": \"https://mcp.sanity.io/developer\",\n      \"type\": \"http\"\n    }\n  }\n}\n```\n\nSee [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.\n\n### Local server prerequisites\n\nBefore you can use the MCP server, you need to:\n\n1. **Deploy your Sanity Studio with schema manifest**\n\n   The MCP server needs access to your content structure to work effectively. Deploy your schema manifest using one of these approaches:\n\n   ```bash\n   cd /path/to/studio\n   npm update sanity\n   npx sanity schema deploy\n   ```\n\n   When running in CI environments without Sanity login, you'll need to provide an auth token:\n\n   ```bash\n   SANITY_AUTH_TOKEN=\u003ctoken\u003e sanity schema deploy\n   ```\n\n\u003e [!NOTE]\n\u003e Schema deployment requires Sanity CLI version 3.88.1 or newer.\n\n2. **Get your API credentials**\n   - Project ID\n   - Dataset name\n   - API token with appropriate permissions\n\nThis MCP server can be used with any application that supports the Model Context Protocol. Here are some popular examples:\n\n- [Claude Desktop](https://modelcontextprotocol.io/quickstart/user)\n- [Cursor IDE](https://docs.cursor.com/context/model-context-protocol)\n- [Visual Studio Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)\n- Custom MCP-compatible applications\n\n### Add configuration for the Sanity MCP server\n\nTo use the Sanity MCP server, add the following configuration to your application's MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"sanity\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@sanity/mcp-server@latest\"],\n      \"env\": {\n        \"SANITY_PROJECT_ID\": \"your-project-id\",\n        \"SANITY_DATASET\": \"production\",\n        \"SANITY_API_TOKEN\": \"your-sanity-api-token\",\n        \"MCP_USER_ROLE\": \"developer\"\n      }\n    }\n  }\n}\n```\n\nFor a complete list of all required and optional environment variables, see the [Configuration section](#️-configuration).\n\nThe exact location of this configuration will depend on your application:\n\n| Application    | Configuration Location                            |\n| -------------- | ------------------------------------------------- |\n| Claude Desktop | Claude Desktop configuration file                 |\n| Cursor         | Workspace or global settings                      |\n| VS Code        | Workspace or user settings (depends on extension) |\n| Custom Apps    | Refer to your app's MCP integration docs          |\n\nYou don't get it to work? See the section on [Node.js configuration](#-nodejs-environment-setup).\n\n## 🛠️ Available Tools\n\n### Context \u0026 Setup \u003c!-- omit in toc --\u003e\n\n- **get_initial_context** – IMPORTANT: Must be called before using any other tools to initialize context and get usage instructions.\n- **get_sanity_config** – Retrieves current Sanity configuration (projectId, dataset, apiVersion, etc.)\n\n### Document Operations \u003c!-- omit in toc --\u003e\n\n- **create_document** – Create a new document with AI-generated content based on instructions\n- **update_document** – Update an existing document with AI-generated content based on instructions\n- **patch_document** - Apply direct patch operations to modify specific parts of a document without using AI generation\n- **transform_document** – Transform document content while preserving formatting and structure, ideal for text replacements and style corrections\n- **translate_document** – Translate document content to another language while preserving formatting and structure\n- **query_documents** – Execute GROQ queries to search for and retrieve content\n- **publish_document** – Publish a draft document to make it live\n- **unpublish_document** – Unpublish a published document (moves it back to drafts)\n- **version_replace_document** – Replace the contents of a document version with contents from another document\n- **version_discard_document** –Discard a document version from a release (removes it from the release)\n- **version_unpublish_document** – Mark a document to be unpublished when the release is run\n- **delete_document** – Permanently delete a document and all its drafts\n\n### Release Management \u003c!-- omit in toc --\u003e\n\n- **list_releases** – List content releases, optionally filtered by state\n- **create_release** – Create a new content release\n- **edit_release** – Update metadata for an existing release\n- **schedule_release** – Schedule a release to publish at a specific time\n- **publish_release** – Publish a release immediately\n- **archive_release** – Archive a release that is no longer active\n- **unarchive_release** – Restore an archived release\n- **unschedule_release** – Remove a previously set schedule from a release\n- **delete_release** – Delete a release\n\n### Version Management \u003c!-- omit in toc --\u003e\n\n- **create_version** – Create a version of a document for a specific release\n- **discard_version** – Delete a specific version document from a release\n- **mark_for_unpublish** – Mark a document to be unpublished when a specific release is published\n\n### Dataset Management \u003c!-- omit in toc --\u003e\n\n- **list_datasets** – List all datasets in the project\n- **create_dataset** – Create a new dataset\n- **update_dataset** – Modify dataset settings\n\n### Schema Information \u003c!-- omit in toc --\u003e\n\n- **get_schema** – Get schema details, either full schema or for a specific type\n- **list_workspace_schemas** – Get a list of all available workspace schema names\n\n### GROQ Support \u003c!-- omit in toc --\u003e\n\n- **get_groq_specification** – Get the GROQ language specification summary\n\n### Embeddings \u0026 Semantic Search \u003c!-- omit in toc --\u003e\n\n- **list_embeddings_indices** – List all available embeddings indices\n- **semantic_search** – Perform semantic search on an embeddings index\n\n### Project Information \u003c!-- omit in toc --\u003e\n\n- **list_projects** – List all Sanity projects associated with your account\n- **get_project_studios** – Get studio applications linked to a specific project\n\n## ⚙️ Configuration\n\nThe server takes the following environment variables:\n\n| Variable                | Description                                                                                                                                                                      | Required |\n| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |\n| `SANITY_API_TOKEN`      | Your Sanity API token                                                                                                                                                            | ✅       |\n| `SANITY_PROJECT_ID`     | Your Sanity project ID                                                                                                                                                           | ✅       |\n| `SANITY_DATASET`        | The dataset to use                                                                                                                                                               | ✅       |\n| `MCP_USER_ROLE`         | Determines tool access level (developer or editor)                                                                                                                               | ✅       |\n| `SANITY_API_HOST`       | API host (defaults to https://api.sanity.io)                                                                                                                                     | ❌       |\n| `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 | ❌       |\n\n\u003e [!WARNING] \n\u003e **Using AI with Production Datasets**  \n\u003e 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.\n\n### 🔑 API Tokens and Permissions\n\nThe MCP server requires appropriate API tokens and permissions to function correctly. Here's what you need to know:\n\n#### Generate API Tokens\n\nFrom the terminal:\n\n```bash\nnpx sanity tokens add \"MCP Server\" --role \u003crole\u003e\n```\n\nOr from Manage:\n\n- Run `npx sanity manage` from your Studio root\n- In your project's management console: Settings \u003e API \u003e Tokens\n- Click \"Add new token\"\n- Create a dedicated token for your MCP server usage (e.g. `mcp-server`)\n- Store the token securely - it's only shown once!\n\n#### Required Permissions\n\nThe token needs appropriate permissions based on your usage\n\n- **For read operations:** `viewer` role is sufficient\n- **For mutations:** `editor` or `developer` role recommended\n- **For project changes** (like managing datasets): `administrator` role may be needed\n\n#### Dataset Access\n\n- **Public datasets:** Content is readable by unauthenticated users\n- **Private datasets:** Require proper token authentication\n- **Draft and versioned content:** Only accessible to authenticated users with appropriate permissions\n\n#### Security Best Practices\n\n- Use separate tokens for different environments (development, staging, production)\n- Never commit tokens to version control\n- Consider using environment variables for token management\n- Regularly rotate tokens for security\n\n### 👥 User Roles\n\nThe server supports two user roles:\n\n- **developer**: Access to all tools\n- **editor**: Content-focused tools without project administration\n\n## 📦 Node.js Environment Setup\n\n\u003e [!IMPORTANT]\n\u003e **For Node Version Manager Users**  \n\u003e 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.\n\n### 🛠 Quick Setup for Node Version Manager Users\n\n1. First, activate your preferred Node.js version:\n\n   ```bash\n   # Using nvm\n   nvm use 20 # or your preferred version\n\n   # Using mise\n   mise use node@20\n\n   # Using fnm\n   fnm use 20\n   ```\n\n2. Then, create the necessary symlinks (choose your OS):\n\n   **On macOS/Linux:**\n\n   ```bash\n   sudo ln -sf \"$(which node)\" /usr/local/bin/node \u0026\u0026 sudo ln -sf \"$(which npx)\" /usr/local/bin/npx\n   ```\n\n   \u003e [!NOTE]\n   \u003e While using `sudo` generally requires caution, it's safe in this context because:\n   \u003e\n   \u003e - We're only creating symlinks to your existing Node.js binaries\n   \u003e - The target directory (`/usr/local/bin`) is a standard system location for user-installed programs\n   \u003e - The symlinks only point to binaries you've already installed and trust\n   \u003e - You can easily remove these symlinks later with `sudo rm`\n\n   **On Windows (PowerShell as Administrator):**\n\n   ```powershell\n   New-Item -ItemType SymbolicLink -Path \"C:\\Program Files\\nodejs\\node.exe\" -Target (Get-Command node).Source -Force\n   New-Item -ItemType SymbolicLink -Path \"C:\\Program Files\\nodejs\\npx.cmd\" -Target (Get-Command npx).Source -Force\n   ```\n\n3. Verify the setup:\n   ```bash\n   # Should show your chosen Node version\n   /usr/local/bin/node --version  # macOS/Linux\n   \"C:\\Program Files\\nodejs\\node.exe\" --version  # Windows\n   ```\n\n### 🤔 Why is this needed?\n\nMCP 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.\n\n### 🔍 Troubleshooting\n\nIf you switch Node versions often:\n\n- Remember to update your symlinks when changing Node versions\n- You can create a shell alias or script to automate this:\n  ```bash\n  # Example alias for your .bashrc or .zshrc\n  alias update-node-symlinks='sudo ln -sf \"$(which node)\" /usr/local/bin/node \u0026\u0026 sudo ln -sf \"$(which npx)\" /usr/local/bin/npx'\n  ```\n\nTo remove the symlinks later:\n\n```bash\n# macOS/Linux\nsudo rm /usr/local/bin/node /usr/local/bin/npx\n\n# Windows (PowerShell as Admin)\nRemove-Item \"C:\\Program Files\\nodejs\\node.exe\", \"C:\\Program Files\\nodejs\\npx.cmd\"\n```\n\n## 💻 Development\n\nInstall dependencies:\n\n```bash\npnpm install\n```\n\nBuild and run in development mode:\n\n```bash\npnpm run dev\n```\n\nBuild the server:\n\n```bash\npnpm run build\n```\n\nRun the built server:\n\n```bash\npnpm start\n```\n\n### Debugging\n\nFor debugging, you can use the MCP inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector \\\n -e SANITY_API_TOKEN=\u003ctoken\u003e \\\n -e SANITY_PROJECT_ID=\u003cproject_id\u003e \\\n -e SANITY_API_HOST=https://api.sanity.io \\\n -e SANITY_DATASET=\u003cds\u003e \\\n -e MCP_USER_ROLE=developer \\\nnode build/index.js\n```\n\nThis will provide a web interface for inspecting and testing the available tools.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanity-io%2Fsanity-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsanity-io%2Fsanity-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanity-io%2Fsanity-mcp-server/lists"}