NocoDB 如何接入 MCP 客户端：创建 MCP Token 并调用数据工具？
【免费下载链接】nocodb🔥 🔥 🔥 A Free & Self-hostable Airtable Alternative项目地址: https://gitcode.com/GitHub_Trending/no/nocodb
如果你的 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 和当前用户。
- 打开目标 Base 的设置页，进入 MCP 设置标签。该页面由 MCP 设置组件 实现。
- 点击右上角的New MCP Endpoint按钮。输入框会自动填入一个默认标题，格式为
Base 标题(工作区标题) : 创建时间，可以改成自己的命名。 - 按回车或点击Save。创建成功后弹出配置弹窗（Modal.vue），里面展示 Token 值和完整的接入 JSON，可直接复制。
- 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 在每次请求中校验该请求头，缺失时返回 401MCP 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)。
验证接入是否成功
在客户端里直接让模型调用工具即可验证，无需额外脚本：
- 先让它调用
getBaseInfo，返回 Base 的 JSON 信息说明端点和 Token 生效； - 再调用
getTablesList，应返回该账号可访问的表列表； - 选一个
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，可对照阅读。
【免费下载链接】nocodb🔥 🔥 🔥 A Free & Self-hostable Airtable Alternative项目地址: https://gitcode.com/GitHub_Trending/no/nocodb
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
