notion

Notion

用于通过 Notion API（https://api.notion.com/v1/，API 版本 2025-09-03）操作 Notion 工作区的工具：查找页面和数据源、读取和创建页面、查询数据源中的行、追加和编辑块内容、管理数据库 / 数据源架构、读取和发布评论。共 24 个脚本，涵盖搜索、读取、写入、架构、评论和跨工作区复制。此版本采用 Notion 的数据源模型：_数据库_是容纳一个或多个_数据源_的容器，而_数据源_包含属性架构和行（页面）。

独立的非官方 Notion 连接器。与 Notion 无关，未获其认可或赞助。“Notion”是其所有者的商标，仅用于标识此连接器所对接的服务。

适用场景

• Agent 需要查找或读取内容时——按标题搜索页面和数据源，然后读取页面、页面的块正文、数据源架构或其中的行。
• Agent 需要创建或编辑页面和内容时——添加页面（数据源中的一行或子页面）、更新属性、追加块，或编辑 / 删除块。
• Agent 需要查询数据源时——筛选和排序数据源中的行，或读取单个页面属性。
• Agent 需要管理架构时——创建或更新数据库和数据源（添加 / 重命名 / 更改类型 / 移除属性），以及读取或发布评论。

设置

这是一个 agentskills.io 技能。

如果尚未将此连接器安装为技能，请先运行 npx skills add zapier/connectors --skill notion 安装（或使用你所用运行环境提供的技能安装机制），然后继续。安装技能只会复制这些文件，不会安装依赖项。运行 CLI、本地 MCP 服务或 zapier-sdk 身份验证命令之前，请先在此处运行一次 npm install --omit=dev。想在自己的项目中将已发布的软件包作为依赖项导入？运行 npm install 时已会解析所有依赖项——参见 references/use-as-sdk.md。

想要查看实际的仓库源码，例如浏览 references/、运行此连接器的测试或修改代码？请参见 README.md，了解如何按需执行 git clone。

此连接器运行于 Node.js 22.18+。请选择与你的运行方式相符的参考文档，并在执行其他操作前先阅读：

你拥有……	阅读
支持 MCP 的客户端——工具可能已加载（例如 mcp__notion__<tool>），也可以自行注册本地服务（或引导用户注册）	references/use-as-mcp.md
终端 / 子进程访问权限（可以运行 node）	references/use-as-cli.md
只有自己的代码，并将此软件包作为依赖项导入	references/use-as-sdk.md
没有工具访问权限、终端或导入此软件包的能力——需要编写自己的代码，直接调用 Notion API（例如在代码执行沙盒中）	references/use-as-recipe.md

脚本

除 copyPage 外，所有脚本都使用单个连接 notion；copyPage 使用两个连接槽（source + target），用于跨工作区复制页面。

脚本	脚本名称	连接	描述
scripts/search.ts	search	notion	按标题搜索页面和数据源（用于解析 ID 的入口）。
scripts/getPage.ts	getPage	notion	按 ID 获取页面的元数据和属性值。
scripts/getDatabase.ts	getDatabase	notion	获取数据库容器及其数据源列表。
scripts/getDataSource.ts	getDataSource	notion	获取数据源的属性架构（名称、类型、选项）。
scripts/queryDataSource.ts	queryDataSource	notion	使用筛选条件和排序规则查询数据源中的行（页面）。
scripts/getBlockChildren.ts	getBlockChildren	notion	列出页面或块的子块（正文内容）。
scripts/getBlock.ts	getBlock	notion	按 ID 获取单个块。
scripts/getPageAsMarkdown.ts	getPageAsMarkdown	notion	以 Markdown 格式获取页面正文内容。
scripts/getPageProperty.ts	getPageProperty	notion	获取单个（分页的）页面属性值。
scripts/listComments.ts	listComments	notion	列出页面或块上未解决的评论。
scripts/listUsers.ts	listUsers	notion	列出工作区用户（成员和机器人）。
scripts/getUser.ts	getUser	notion	按 ID 获取单个用户。
scripts/getBotUser.ts	getBotUser	notion	获取当前令牌对应的机器人用户（集成身份）。
scripts/createPage.ts	createPage	notion	创建页面：数据源中的一行（parent.data_source_id）或子页面（parent.page_id）。
scripts/updatePage.ts	updatePage	notion	更新页面的属性、图标、封面、父级（移动）或回收站状态（in_trash）。
scripts/appendBlockChildren.ts	appendBlockChildren	notion	在页面或块的末尾追加内容块。
scripts/updateBlock.ts	updateBlock	notion	更新单个块的内容或将其归档。
scripts/deleteBlock.ts	deleteBlock	notion	删除块（将其移至回收站；可恢复）。
scripts/createDatabase.ts	createDatabase	notion	在页面下创建数据库，并设置初始数据源架构。
scripts/updateDatabase.ts	updateDatabase	notion	更新数据库容器的标题、图标、封面、父级、内嵌状态或回收站状态。
scripts/createDataSource.ts	createDataSource	notion	向现有数据库添加新的数据源（架构）。
scripts/updateDataSource.ts	updateDataSource	notion	更新数据源架构（添加、重命名、更改类型或移除属性）。
scripts/createComment.ts	createComment	notion	在页面上添加评论，或回复现有讨论串。
scripts/copyPage.ts	copyPage	source, target	将页面（标题和顶层块）从一个工作区复制到另一个工作区。需要两个 Notion 连接。

消歧与拒绝

写入前先消歧。 在写入按名称查找的页面或行之前（例如，更新通过 search 找到的页面，或通过 queryDataSource 找到的行），请统计大小写不敏感的精确标题匹配项：

• 恰好匹配一项 — 对其执行操作。不要过度追问；只有一个明确匹配项时，它就是答案。
• 有两个或更多并列匹配项 — 停止。列出这些并列候选项，并附上用于区分的字段（parent、url 或 last_edited_time），询问用户指的是哪一个。不要随意选择，也不要写入所有匹配项。

不支持的操作——说明这一点并停止；不要假装用其他工具来完成。 本目录有意不提供以下功能：

• 永久删除任何内容。所有内容都只能移入垃圾箱或恢复——页面通过 updatePage 设置 in_trash，块通过 deleteBlock 删除（可撤销）。没有彻底删除功能。
• 删除整个数据库或数据源。 没有相应工具。不要通过将每一行移入垃圾箱来模拟此操作。
• 管理工作区成员或权限（邀请用户、更改角色、共享）。listUsers / getUser 仅支持读取。
• 创建或管理数据库视图。 API 不提供视图。

如果用户要求执行上述任何操作，请告知用户不支持，然后停止——不要尝试调用无关工具来近似实现。

身份验证

每种形态都会将身份验证信息作为一个连接选择器传递，而不是密钥——格式为 [<resolver>:]<value>。每个连接器都接受 zapier:<connection-id>（由 Zapier 管理的身份验证——通过 Zapier 的身份验证、重试和治理层进行路由）；有些连接器还接受一个或多个直接令牌解析器（名称和数量因连接器而异），请检查此连接器自己的解析器，不要想当然。<resolver>: 前缀是可选的；裸值会交给第一个认领它的解析器——UUID 形式的裸值始终会由 zapier: 认领。每个脚本都会声明所需的连接及其接受的解析器。传递连接的确切语法（以及如何查看此连接器的解析器列表）因形态而异——请参阅上文加载的参考文档。

想先检查已配置的内容？不要通过输出环境变量值来检查——env 或 env | grep <name> 会同时打印变量名和值；如果其中设置了有效凭据，就会将其泄露到对话记录中。只检查变量名（env | cut -d= -f1 | grep -i <name>），或直接测试已知变量名（[ -n "$VAR_NAME" ]）。

还没有连接？选择一种方式——并遵循相应参考文档中的流程来获取连接；不要直接向用户索要连接 ID 或令牌，仿佛他们早已记得这些信息：

	加载
直接传递凭据	references/use-without-zapier.md
通过 Zapier 连接进行路由	references/use-with-zapier.md

输出格式

每个脚本都会返回一个 { data, meta } 信封：

• data — 脚本的结果（其形状由 outputSchema 声明；请参阅上方加载的参考资料，了解如何检查脚本在你所用形状中的确切架构）。
• meta.outputDataValidation — 对 data 进行验证的结果：
  • { skipped: false, droppedPaths: null } — 已验证，没有移除任何内容。
  • { skipped: false, droppedPaths: [...], instruction } — 已验证，但这些路径已从 data 中剔除：脚本从 API 返回、但 outputSchema 未声明的字段。如果需要这些字段，请重新运行并跳过输出验证。
  • { skipped: true } — 已绕过验证；data 是未经检查的脚本原始输出。

读取被剔除的字段 / skipOutputDataValidation。 若要接收未经验证的原始结果，请选择退出输出验证（具体语法因形状而异，参阅上方加载的参考资料）。输入验证始终不会跳过。

精简结果 / filterOutputData。 若要将大型结果缩减为所需字段，请传入一个对 data 进行后处理的 jq 表达式（具体语法同样因形状而异）。jq 只会针对 data 运行，而非 { data, meta } 信封，因此表达式应以 data 为根（运行脚本的 --help，或你所用形状的等效命令，查看其输出架构）。转换后的值会替换 data，meta 保持不变，且结果不会再根据输出架构进行验证。

参考资料

在处理相应内容前，先加载匹配的参考文件：

参考资料	涵盖内容	何时加载
references/notion-api-gotchas.md	版本管理 + 2025-09-03 数据源模型、身份验证/共享、错误封装 + 代码表、速率限制、大小限制、分页、ID/URL 格式、归档/回收站、仅搜索标题、25 个引用的截断。	调试错误或 404、对列表分页、解析 ID，或梳理数据库与数据源之间的区别时。
references/notion-blocks.md	类型化区块对象、常见区块类型、rich_text 的结构、追加子项（限制 + 嵌套），以及 updateBlock 无法更改区块类型的原因。	构建或编辑页面内容时——使用 appendBlockChildren、createPage（children）、updateBlock。
references/notion-properties.md	属性架构对象 + 类型列表，以及各类型页面属性的值结构。	定义架构（createDatabase、createDataSource）或写入属性值（createPage、updatePage）时。
references/notion-query.md	filter 对象（单一条件 + 组合 and/or）、各类型的条件、sorts 数组、10,000 条结果上限。	使用筛选或排序调用 queryDataSource 时。