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

[!NOTE] 此仓库已存档且不再积极维护。 我们现在推荐使用托管服务器 mcp.sanity.io，它提供流式HTTP传输、OAuth认证、持续更新的工具以及无需本地设置即可使用的生产级可靠性。

使用AI驱动的工具来革新您的内容操作。通过您喜欢的AI启用编辑器中的自然语言对话创建、管理和探索您的内容。

Sanity MCP Server 实现了 Model Context Protocol，以连接您的Sanity项目与AI工具如Claude、Cursor和VS Code。它使AI模型能够理解您的内容结构并通过自然语言指令执行操作。

✨ 主要特性 <!-- omit in toc -->

• 🤖 内容智能：让AI探索并理解您的内容库
• 🔄 内容操作：通过自然语言指令自动化任务
• 📊 模式感知：AI尊重您的内容结构和验证规则
• 🚀 发布管理：轻松计划和组织内容发布
• 🔍 语义搜索：基于意义而非仅关键词查找内容

目录 <!-- omit in toc -->

• 🔌 快速开始
  • 远程服务器（首选）
  • 本地服务器前提条件
  • 添加Sanity MCP服务器配置
• 🛠️ 可用工具
• ⚙️ 配置
  • 🔑 API令牌和权限
    • 生成API令牌
    • 所需权限
    • 数据集访问
    • 安全最佳实践
  • 👥 用户角色
• 📦 Node.js环境设置
  • 🛠 快速设置用于Node版本管理器用户
  • 🤔 为什么需要这一步？
  • 🔍 故障排除
• 💻 开发
  • 调试

🔌 快速开始

远程服务器（首选）

托管在 mcp.sanity.io 的服务器支持现代流式HTTP传输和OAuth认证。将以下配置添加到您的MCP客户端中：

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

远程服务器的好处：

• 流式HTTP以获得更好的性能
• OAuth进行安全认证（无需管理令牌）
• 自动获取最新工具和功能
• 不需要Node.js设置

请参阅 mcp.sanity.io 获取完整的安装说明，适用于Claude Code、Cursor和其他MCP客户端。

---

注意： 下面的本地服务器说明仅适用于自托管。此仓库已存档且不再维护。

本地服务器前提条件

在您可以使用MCP服务器之前，您需要：

1. 部署您的Sanity Studio带有模式清单

   MCP服务器需要访问您的内容结构才能有效工作。使用以下方法之一部署您的模式清单：

   cd /path/to/studio
   npm update sanity
   npx sanity schema deploy
   

   在CI环境中运行而没有Sanity登录时，您需要提供一个认证令牌：

   SANITY_AUTH_TOKEN=<token> sanity schema deploy
   

[!NOTE] 模式部署需要Sanity CLI版本3.88.1或更高版本。

2. 获取您的API凭证
   • 项目ID
   • 数据集名称
   • 具有适当权限的API令牌

此MCP服务器可以与任何支持Model Context Protocol的应用程序一起使用。这里是一些流行的例子：

• Claude Desktop
• Cursor IDE
• Visual Studio Code
• 自定义MCP兼容应用程序

添加配置对于Sanity MCP服务器

要使用Sanity MCP服务器，请向您的应用程序的MCP设置添加以下配置：

{
  "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"
      }
    }
  }
}

有关所有必需和可选环境变量的完整列表，请参阅 配置部分。

此配置的确切位置取决于您的应用程序：

应用程序	配置位置
Claude Desktop	Claude Desktop配置文件
Cursor	工作区或全局设置
VS Code	工作区或用户设置（取决于扩展）
自定义应用	参考您的应用MCP集成文档

无法正常工作？请参阅 Node.js配置 部分。

🛠️ 可用工具

上下文及设置 <!-- omit in toc -->

• get_initial_context – 重要：必须在使用其他任何工具之前调用，以初始化上下文并获取使用说明。
• get_sanity_config – 获取当前Sanity配置（projectId、dataset、apiVersion等）。

文档操作 <!-- omit in toc -->

• create_document – 根据指令创建具有AI生成内容的新文档
• update_document – 根据指令更新现有文档的内容
• patch_document - 对文档的特定部分应用直接修补操作，不使用AI生成
• transform_document – 转换文档内容同时保留格式和结构，适合文本替换和样式修正
• translate_document – 将文档内容翻译成另一种语言同时保留格式和结构
• query_documents – 执行GROQ查询以搜索和检索内容
• publish_document – 发布草稿文档使其生效
• unpublish_document – 取消发布已发布的文档（将其移回草稿）
• version_replace_document – 替换文档版本的内容来自另一个文档
• version_discard_document – 从发布中丢弃文档版本（将其从发布中删除）
• version_unpublish_document – 标记文档在发布运行时取消发布
• delete_document – 永久删除文档及其所有草稿

发布管理 <!-- omit in toc -->

• list_releases – 列出内容发布，可选按状态过滤
• create_release – 创建新的内容发布
• edit_release – 更新现有发布的元数据
• schedule_release – 安排发布在特定时间发布
• publish_release – 立即发布发布
• archive_release – 归档不再活跃的发布
• unarchive_release – 恢复归档的发布
• unschedule_release – 移除已安排的发布时间
• delete_release – 删除发布

版本管理 <!-- omit in toc -->

• create_version – 为特定发布创建文档的版本
• discard_version – 从发布中删除特定版本文档
• mark_for_unpublish – 标记文档在特定发布时取消发布

数据集管理 <!-- omit in toc -->

• list_datasets – 列出项目中的所有数据集
• create_dataset – 创建新的数据集
• update_dataset- 修改数据集设置

模式信息 <!-- omit in toc -->

• get_schema – 获取模式详情，可以是完整模式或特定类型
• list_workspace_schemas – 获取所有可用工作区模式名称的列表

GROQ支持 <!-- omit in toc -->

• get_groq_specification – 获取GROQ语言规范摘要

嵌入式及语义搜索 <!-- omit in toc -->

• list_embeddings_indices – 列出所有可用嵌入索引
• semantic_search – 在嵌入索引上执行语义搜索

项目信息 <!-- omit in toc -->

• list_projects – 列出与您的帐户关联的所有Sanity项目
• get_project_studios – 获取与特定项目关联的工作室应用

⚙️ 配置

服务器接受以下环境变量：

变量	描述	必需
SANITY_API_TOKEN	您的Sanity API令牌	✅
SANITY_PROJECT_ID	您的Sanity项目ID	✅
SANITY_DATASET	要使用的数据集	✅
MCP_USER_ROLE	决定工具访问级别（开发者或编辑者）	✅
SANITY_API_HOST	API主机（默认为https://api.sanity.io）	❌
MAX_TOOL_TOKEN_OUTPUT	工具响应的最大令牌输出（默认为50000）。根据您的模型上下文限制进行调整。更高的限制可能会因过多数据而污染对话上下文	❌

[!WARNING] 使用AI与生产数据集
当使用具有写入权限的令牌配置MCP服务器时，请注意AI可以执行破坏性操作，例如创建、更新或删除内容。如果您使用的是只读令牌，则这不是问题。虽然我们正在积极开发防护措施，但您应该谨慎行事，并考虑使用开发/测试数据集来测试需要写入权限的AI操作。

🔑 API令牌和权限

MCP服务器需要适当的API令牌和权限才能正确运行。以下是您需要了解的信息：

生成API令牌

从终端：

npx sanity tokens add "MCP Server" --role <role>

或者从管理：

• 在您的工作室根目录运行 npx sanity manage
• 在您的项目管理控制台中：设置 > API > 令牌
• 单击“添加新令牌”
• 为您的MCP服务器使用创建专用令牌（例如 mcp-server）
• 安全存储令牌——它只会显示一次！

所需权限

令牌需要基于您的使用情况的适当权限

• 对于读取操作： viewer 角色足够
• 对于变更操作： 推荐 editor 或 developer 角色
• 对于项目更改（如管理数据集）：可能需要 administrator 角色

数据集访问

• 公共数据集： 内容可由未认证用户阅读
• 私有数据集： 需要适当的令牌认证
• 草稿和版本化内容： 只能被具有适当权限的认证用户访问

安全最佳实践

• 为不同环境（开发、测试、生产）使用单独的令牌
• 绝不要将令牌提交到版本控制系统
• 考虑使用环境变量进行令牌管理
• 定期轮换令牌以确保安全

👥 用户角色

服务器支持两种用户角色：

• 开发者：访问所有工具
• 编辑者：专注于内容的工具，无项目管理

📦 Node.js环境设置

[!IMPORTANT] 对于Node版本管理器用户
如果您使用 nvm、mise、fnm、nvm-windows 或类似工具，您需要按照下面的步骤设置，以确保MCP服务器可以访问Node.js。这是一个一次性设置，可以节省您以后的故障排查时间。这是一个 正在进行的问题 与MCP服务器。

🛠 快速设置用于Node版本管理器用户

1. 首先，激活您选择的Node.js版本：

   # 使用nvm
   nvm use 20 # 或您选择的版本
   
   # 使用mise
   mise use node@20
   
   # 使用fnm
   fnm use 20
   

2. 然后，创建必要的符号链接（选择您的操作系统）：

   在macOS/Linux上：

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

   [!NOTE] 虽然通常使用 sudo 需要谨慎，但在这种情况下是安全的，因为：

   • 我们只是创建指向您已安装和信任的二进制文件的符号链接
   • 目标目录（/usr/local/bin）是标准系统位置，用于用户安装的程序
   • 符号链接只指向您已安装和信任的二进制文件
   • 您稍后可以轻松地使用 sudo rm 删除这些符号链接

   在Windows（管理员身份运行的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. 验证设置：

   # 应该显示您选择的Node版本
   /usr/local/bin/node --version  # macOS/Linux
   "C:\Program Files\nodejs\node.exe" --version  # Windows
   

🤔 为什么需要这一步？

MCP服务器通过直接调用 node 和 npx 二进制文件启动。当使用Node版本管理器时，这些二进制文件是在隔离环境中管理的，系统应用程序不能自动访问。上面的符号链接创建了一个桥梁，连接您的版本管理器和MCP服务器使用的系统路径。

🔍 故障排除

如果您经常切换Node版本：

• 记得在更改Node版本时更新符号链接
• 您可以创建一个shell别名或脚本来自动化此过程：

  # 示例别名，用于您的 .bashrc 或 .zshrc
  alias update-node-symlinks='sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx'
  

要稍后删除符号链接：

# macOS/Linux
sudo rm /usr/local/bin/node /usr/local/bin/npx

# Windows（管理员身份运行的PowerShell）
Remove-Item "C:\Program Files\nodejs\node.exe", "C:\Program Files\nodejs\npx.cmd"

💻 开发

安装依赖项：

pnpm install

构建并运行在开发模式：

pnpm run dev

构建服务器：

pnpm run build

运行构建的服务器：

pnpm start

调试

对于调试，您可以使用MCP检查器：

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

这将提供一个Web界面，用于检查和测试可用工具。