NocoDB 如何接入 MCP 客户端：创建 MCP Token 并调用数据工具？

如果你的 NocoDB 实例里已经有一个 Base（数据库），想让 Claude Desktop、Cursor、Windsurf 这类支持 MCP（Model Context Protocol）的客户端直接读写其中的数据，需要完成两件事：在 Base 设置里创建一个 MCP Token，然后把 NocoDB 生成的 MCP 接入配置填进客户端。配置成功后，客户端能通过 getTablesList、queryRecords 等工具查询表结构和记录，有权限时还能创建、更新、删除记录。

前提：一个可访问的 NocoDB 实例，一个对目标 Base 有权限的用户账号。MCP 端点、Token 和数据工具都由服务端内置，不需要额外安装服务端组件；客户端一侧依赖 npx mcp-remote 转发。

在 Base 设置中创建 MCP Token

MCP Token 是端点身份凭证，绑定到创建它的 Base 和当前用户。

1. 打开目标 Base 的设置页，进入 MCP 设置标签。该页面由 MCP 设置组件 实现。
2. 点击右上角的 New MCP Endpoint 按钮。输入框会自动填入一个默认标题，格式为 Base 标题(工作区标题) : 创建时间，可以改成自己的命名。
3. 按回车或点击 Save。创建成功后弹出配置弹窗（Modal.vue），里面展示 Token 值和完整的接入 JSON，可直接复制。
4. Token 列表页只显示名称和创建时间，不显示 Token 值。如果 Token 泄露或需要换端点，在列表行菜单里选择 Regenerate Token 重新生成，旧值随之失效；Delete Token 则直接删除该端点。

账号设置页另有一个账号级 MCP 视图，通过 mcpRootList 操作列出账号名下的 Token（见 useMcpSettings.ts），方便在多 Base 场景下集中查看。

填入客户端的 MCP 接入配置

创建 Token 后，弹窗按客户端分 Tab（Claude / Cursor / Windsurf / AntiGravity），每个 Tab 给出相同的 JSON 配置，由 Modal.vue 动态生成：

{
  "mcpServers": {
    "NocoDB - <Base 标题>": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "<NocoDB 站点地址>/mcp/<tokenId>",
        "--header",
        "xc-mcp-token: <token>"
      ]
    }
  }
}

各部分来源：

• 服务器名 NocoDB - <Base 标题> 由 Base 标题拼出（企业版会带上工作区名）；
• URL 是实例站点地址（源码中的 ncSiteUrl）加 /mcp/<tokenId>，tokenId 是刚创建的 Token 的 id；
• --header 里的 xc-mcp-token: <token> 中填 Token 值。服务端 mcp.controller.ts 在每次请求中校验该请求头，缺失时返回 401 MCP token missing。

弹窗提供的三个客户端配置路径：

• Claude Desktop：从导航栏打开设置 → Develop 标签 → 点击 Edit Config → 把 JSON 粘贴进 claude_desktop_config.json；
• Cursor：Shift+Cmd+J 打开 Cursor 设置 → MCP 标签 → Add Custom MCP → 粘贴 JSON；
• Windsurf：设置 → 左侧 Cascade 标签 → Manage MCP → View raw config → 在打开的文件里粘贴 JSON。

客户端可以调用的数据工具

端点通过 MCP Streamable HTTP 传输暴露工具（mcp.service.ts）。所有工具都作用在 Token 所属的那个 Base 上，可用的工具集由创建人对该 Base 的角色决定：

工具	用途	参数
getBaseInfo	获取当前 Base 信息	无
getTablesList	列出用户可访问的表	无
getTableSchema	获取表的字段与视图信息	tableId
queryRecords	分页查询记录	tableId、pageSize（默认 50，上限 200）、page、where、sort、fields
getRecord	按 ID 取单条记录	tableId、recordId、fields（逗号分隔）
countRecords	统计记录数	tableId、where
readAttachment	读取记录中的附件并提取文本	files（附件对象数组）
aggregate_single	对表做聚合（sum/avg/count/earliest_date 等）	tableId、aggregations、where、viewId

写操作工具只有当 Token 创建人在该 Base 的角色达到 Editor 及以上时才会注册：

• createRecords：tableId + records（字段名到值的键值对数组）；
• updateRecords：tableId + records（含记录 id 和要更新的字段）；
• deleteRecords：tableId + records（含要删除的记录 id 数组）。

另外，源码中 aggregate_single 在非企业版（!isEE）构建中才注册，具体以你所运行的版本为准。

where 过滤语法

queryRecords、countRecords、aggregate_single 的 where 参数使用 NocoDB 查询语法，规则完整列在 descriptions.ts：

• 基本形式 (field,operator,value)，例如 (name,eq,John)、(status,in,active,pending,review)、(price,gt,100)；
• 多条件组合必须用带波浪线的逻辑符：(name,eq,John)~and(age,gte,18)，写普通 and/or 会报错；否定用 ~not；
• 日期字段必须带子操作符，直接写日期会被拒绝。正确写法是 (due_date,eq,exactDate,2026-06-01)，而不是 (due_date,eq,2026-06-01)；相对日期如 (created_at,isWithin,pastWeek)、(due_date,lt,today)；
• 文档给出的组合示例：(status,eq,active)~and(created_at,isWithin,pastMonth)（本月激活的用户）、(amount,gte,100)~and(amount,lte,500)~and(status,in,pending,processing)。

验证接入是否成功

在客户端里直接让模型调用工具即可验证，无需额外脚本：

1. 先让它调用 getBaseInfo，返回 Base 的 JSON 信息说明端点和 Token 生效；
2. 再调用 getTablesList，应返回该账号可访问的表列表；
3. 选一个 tableId 调用 getTableSchema 和 queryRecords（例如 queryRecords 传 tableId 和 where: "(created_at,isWithin,pastWeek)"），返回的记录是格式化 JSON 文本。

出现以下报错时按源码中的分支判断：

• 响应为 401 且提示 MCP token missing：请求里没有 xc-mcp-token 请求头，检查客户端配置里 --header 一行是否完整粘贴；
• 403 User has no access：Token 创建人在该 Base 的角色是 no_access，需要先在 Base 成员设置中给该账号分配角色；
• 工具返回 Error: Table "<tableId>" not found：tableId 不属于当前 Base 或账号不可见，先用 getTablesList 确认实际可用的表 ID。

使用边界

• Token 与 Base 绑定，工具只能访问 Token 所属 Base 的数据；能看到的表和能写的记录都受创建人在该 Base 的权限限制，MCP 不会放大权限。
• queryRecords 的 pageSize 会被钳制在 1–200 之间，深分页靠 page 参数翻页。
• 换 Token 值或删 Token 后，旧端点立即不可用，需要重新生成接入配置并更新客户端。

服务端路由入口见 mcp.controller.ts，工具注册与参数定义见 mcp.service.ts，Token 校验模型见 MCPToken.ts，可对照阅读。