钉钉 AI 表格操作（新版 MCP）

🚀 5 分钟快速开始

1️⃣ 列出我的表格

mcporter call '<DINGTALK_MCP_URL>' .list_bases limit=5

2️⃣ 创建新表格

mcporter call '<DINGTALK_MCP_URL>' .create_base baseName='我的项目'

3️⃣ 添加记录

mcporter call '<DINGTALK_MCP_URL>' .create_records \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_name":"张三"}}]}'

4️⃣ 查询记录

mcporter call '<DINGTALK_MCP_URL>' .query_records \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","limit":10}'

5️⃣ 批量导入

python3 scripts/import_records.py base_xxx tbl_xxx data.csv

核心概念

按 新版 MCP schema 工作：

Base：
```
baseId
```
Table：
```
tableId
```
Field：
```
fieldId
```
Record：
```
recordId
```

不要再用旧版

dentryUuid / sheetIdOrName / fieldIdOrName

。

推荐使用

mcporter 0.8.1

及以上版本。

输出模式兼容说明：

```
mcporter 0.8.1+
```
可直接调用
更低版本需要显式加
```
--output text
```
AI 表格 MCP 无论使用哪种模式，返回体本身都是标准 JSON；差异主要在
```
mcporter
```
的输出处理方式

版本守门规则（每个 MCP Server 地址只强制检查一次）

在真正开始任何 AI 表格操作前，必须先检查当前

mcporter

注册的

dingtalk-ai-table

MCP server 实际返回的 tools schema。但这个检查不该每次都重复做；同一个 MCP Server 地址只需要强制检查一次。

一次性检查策略

先读取当前
```
mcporter
```
里
```
dingtalk-ai-table
```
对应的 MCP Server 地址。
用这个地址生成一个本地检查标记（例如基于完整 URL 或其 hash）。
在工作区保存检查结果，例如放到：

~/.openclaw/workspace/.cache/dingtalk-ai-table/

建议文件名模式：

schema-check-<url-hash>.json

如果当前地址对应的检查标记已经存在，并且结果是“已确认新版 schema”，则跳过重复检查，直接继续后续 AI 表格操作。
只有在以下情况才重新强制检查：
- 第一次运行，没有检查标记
- ```
mcporter
```
  里的 MCP Server 地址变了
- 之前检查结果是旧版 schema / 检查失败
- 用户明确要求重新验证

强制检查时执行

mcporter list dingtalk-ai-table --schema

判断标准

如果返回的 tools 仍然是旧版这一套，例如出现：

```
get_root_node_of_my_document
```
```
create_base_app
```
```
list_base_tables
```
```
add_base_record
```
```
search_base_record
```
```
list_base_field
```

或者整体仍然基于：

```
dentryUuid
```
```
sheetIdOrName
```
```
fieldIdOrName
```

那么说明：虽然 skill 文件已经是新版，但 mcporter 里注册的 MCP server 地址还是旧的，不能继续操作。

遇到旧版 schema 时的强制提示

此时必须明确提示用户：

打开这个页面：

https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail

点击右侧 「获取 MCP Server 配置」 按钮
复制新的 MCP Server 地址
用新的地址替换
```
mcporter
```
里已经注册的
```
dingtalk-ai-table
```
地址
替换完成后，再重新执行：

mcporter list dingtalk-ai-table --schema

只有当返回的 tools 已经变成新版 schema，例如出现：

```
list_bases
```
```
get_base
```
```
get_tables
```
```
get_fields
```
```
query_records
```
```
create_records
```
```
update_records
```
```
delete_records
```
```
prepare_attachment_upload
```

才允许继续真正的 AI 表格操作。

通过检查后的处理

一旦确认当前 MCP Server 地址返回的是新版 schema，就把结果写入本地检查标记。后续只要

mcporter

里的

dingtalk-ai-table

地址没变，就不要再重复做这一步守门检查。

用户提示文案（可直接复用）

当前 mcporter 里注册的 dingtalk-ai-table 还是旧版 MCP schema，暂时不能按新版技能操作。
请打开 https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail ，点击右侧“获取 MCP Server 配置”按钮，复制新的 MCP Server 地址，并替换 mcporter 里已注册的 dingtalk-ai-table 地址。替换后重新检查 schema，确认出现 list_bases / get_base / create_records 等新版 tools 后，再继续操作 AI 表格。

前置要求

安装 mcporter CLI

npm install -g mcporter
# 或
bun install -g mcporter

验证：

mcporter --version

配置 MCP Server

在钉钉 MCP 广场 https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail 获取新版钉钉 AI 表格 MCP 的

Streamable HTTP URL

。

方式一：直接配置到 mcporter

mcporter config add dingtalk-ai-table --url "<Streamable_HTTP_URL>"

方式二：使用环境变量

export DINGTALK_MCP_URL="<Streamable_HTTP_URL>"

这个 URL 带访问令牌，等同密码，不要泄露。

工作区沙箱

脚本读取本地文件时，会优先使用

OPENCLAW_WORKSPACE

作为允许根目录：

export OPENCLAW_WORKSPACE="$HOME/.openclaw/workspace"

未设置时默认使用当前工作目录。

核心工具集

Base 层

```
list_bases
```
```
search_bases
```
```
get_base
```
```
create_base
```
```
update_base
```
```
delete_base
```
```
search_templates
```

Table 层

```
get_tables
```
```
create_table
```
```
update_table
```
```
delete_table
```

Field 层

```
get_fields
```
```
create_fields
```
```
update_field
```
```
delete_field
```

Record 层

```
query_records
```
```
create_records
```
```
update_records
```
```
delete_records
```

附件层

```
prepare_attachment_upload
```

推荐工作流

1. 先找 Base

mcporter call dingtalk-ai-table list_bases limit=10
mcporter call dingtalk-ai-table search_bases query="销售"

2. 再拿 Table 目录

mcporter call dingtalk-ai-table get_base baseId="base_xxx"

3. 再展开表结构

mcporter call dingtalk-ai-table get_tables \
  --args '{"baseId":"base_xxx","tableIds":["tbl_xxx"]}'

4. 字段复杂时读完整配置

mcporter call dingtalk-ai-table get_fields \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","fieldIds":["fld_xxx"]}'

5. 再查 / 写记录

mcporter call dingtalk-ai-table query_records \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","limit":20}'
mcporter call dingtalk-ai-table create_records 

--args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_name":"张三"}}]}'

6. 写入附件字段

attachment 字段支持三种写法：

方式一：先上传，再写 fileToken（推荐，可靠）

# Step 1：申请上传地址（返回 uploadUrl 和 fileToken）
mcporter call dingtalk-ai-table prepare_attachment_upload \
  --args '{"baseId":"base_xxx","fileName":"report.pdf","size":102400,"mimeType":"application/pdf"}'
Step 2：把文件 PUT 到 uploadUrl（必须带 Content-Type，值必须与 mimeType 完全一致）
curl -X PUT "<uploadUrl>" 

-H "Content-Type: application/pdf" 

--data-binary @report.pdf
Step 3：把 fileToken 写入记录
mcporter call dingtalk-ai-table create_records 

--args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_attach":[{"fileToken":"ft_xxx"}]}}]}'

方式二：直接传外链 URL（异步转存，best-effort）

mcporter call dingtalk-ai-table create_records \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_attach":[{"url":"https://example.com/file.pdf"}]}}]}'

URL 转存是 best-effort 异步链路，返回成功仅表示已受理，不保证立即可读。可靠写入请用 fileToken 方式。

方式三：原样回传已有附件数据（保留 / 追加已有附件时使用）

从

query_records

读出的 attachment 单元格数据是完整对象数组，字段形状如下：

[
  {
    "filename": "a.xlsx",
    "size": 92250,
    "type": "xls",
    "resourceId": "<id>",
    "resourceUrl": "<resourceUrl>"
  }
]

其中

type

是文件类别枚举，常见值为

"xls"

、

"image"

等；

resourceUrl

通常为有时效的下载链接。

如需保留已有附件，把读出的值原样塞回即可。如需追加新附件，把新的

{"fileToken":"ft_xxx"}

与已有对象合并成一个数组一起传入。

update_records

的 attachment 字段格式相同，传入后会整体覆盖该字段。

脚本

批量新增字段

python3 scripts/bulk_add_fields.py <baseId> <tableId> fields.json

fields.json

示例：

[
  {"fieldName":"任务名","type":"text"},
  {"fieldName":"优先级","type":"singleSelect","config":{"options":[{"name":"高"},{"name":"中"},{"name":"低"}]}}
]

兼容项：

```
name
```
会自动映射为
```
fieldName
```
```
phone
```
会自动映射为
```
telephone
```

批量导入记录

python3 scripts/import_records.py <baseId> <tableId> data.csv
python3 scripts/import_records.py <baseId> <tableId> data.json 50

说明：

CSV 表头默认按
```
fieldId
```
解释

JSON 支持：

```
[{"cells": {...}}]
```
```
[{"fld_xxx": "value"}]
```

安全规则

文件路径受
```
OPENCLAW_WORKSPACE
```
沙箱限制
仅允许读取工作区内
```
.json
```
/
```
.csv
```
文件
Base / Table / Field / Record ID 都做格式校验
批量上限按 MCP server 实际限制控制：
- ```
create_fields
```
  ：最多 15
- ```
get_tables / get_fields
```
  ：最多 10
- ```
create_records / update_records / delete_records
```
  ：最多 100

调试原则

先
```
get_base
```
，再
```
get_tables
```
，必要时
```
get_fields
```
不要猜
```
fieldId
```
复杂参数一律用
```
--args
```
JSON
```
singleSelect / multipleSelect
```
过滤时必须传 option ID，不是 option name

参考

API 参考：
```
references/api-reference.md
```
错误排查：
```
references/error-codes.md
```

Dingtalk Ai Table

AI Skill Market Insights

Be Part of the 0+ Developer Community