Notion Api Toolkit Free

轻量级Notion API集成工具，支持托管OAuth鉴权、页面数据库查询与基础读写，适合个人快速接入和管理工作空间。

Notion API工具箱(免费版)

一个面向个人开发者与知识工作者的轻量化Notion集成Skill,通过托管OAuth与REST API的组合,帮助你快速接入Notion工作空间。本免费版聚焦查询与基础读写,适合个人与小型团队试用。

概述

本Skill封装了Notion API的常用操作,通过托管OAuth代理层屏蔽鉴权复杂度。所有写操作(创建、更新、删除)均需用户明确确认目标资源与连接,保障数据安全。免费版适合日请求量不超过500次的场景。

核心能力

能力	描述	免费版是否支持
OAuth鉴权	托管OAuth,无需自建	支持(单连接)
页面查询	搜索、获取、创建页面	支持
数据库检索	查询数据库、获取数据源	支持
块管理	读取、追加、删除块	支持
用户信息	列出用户、获取当前用户	支持
写操作确认	强制用户确认目标	支持
多连接管理	同时管理多个Notion账户	不支持
批量操作	批量创建/更新页面	不支持
Webhook订阅	页面变更事件推送	不支持
高级筛选	复合条件筛选	部分支持
分页自动化	自动翻页	不支持
版本管理	API版本切换	不支持

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：轻量化、集成工具、数据库检索与基础、适合个人快速接入、工作空间、工具箱、是面向个人开发者、与知识工作者的轻、通过托管、REST、的组合、帮助用户在数分钟、内接入、核心能力等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一:个人知识库检索

个人开发者希望快速检索自己的Notion笔记。

bash

# 1. 登录并创建连接
notion-toolkit login
notion-toolkit connection create
# ...
# 2. 搜索页面
notion-toolkit search "会议纪要"
# ...
# 3. 查询数据库
notion-toolkit database query <databaseId> --filter '{"property":"Status","select":{"equals":"Active"}}'

场景二:小型团队页面读取

团队成员需要读取共享的Notion文档。

bash

# 获取页面内容
notion-toolkit page view <pageId>
# ...
# 读取块级内容
notion-toolkit block children <blockId>
# ...
# 获取当前用户信息
notion-toolkit whoami

场景三:简单页面创建

开发者希望在Notion中自动创建任务页面。

bash

# 用户确认后创建页面
notion-toolkit page create --parent-page <parentId> --title "新任务"
# ...
# 追加内容块
notion-toolkit block append <pageId> --children '[{"type":"paragraph","paragraph":{"rich_text":[{"text":{"content":"任务详情"}}]}}]'

不适用场景

以下场景Notion API工具箱(免费版)不适合处理：

• 逆向工程闭源API
• API安全渗透测试
• 非标准协议集成

触发条件

需要API集成、接口对接、Webhook配置、系统连接时使用。不适用于非本工具能力范围的需求。

快速开始

预计上手时间:<60秒。

依赖详情

bash

npm install -g notion-api-toolkit

Step 2:登录并创建连接

bash

notion-toolkit login
notion-toolkit connection create notion
# 返回的URL在浏览器中打开,完成OAuth授权

Step 3:验证连接

bash

notion-toolkit connection list
notion-toolkit whoami

Step 4:开始查询

bash

notion-toolkit search "你的关键词"

示例

鉴权配置

bash

# 设置API Key
export NOTION_TOOLKIT_API_KEY="your_api_key_here"
# ...
# 验证鉴权状态
notion-toolkit whoami

基础查询示例

bash

# 搜索页面
notion-toolkit search "会议" --filter page
# ...
# 搜索数据源
notion-toolkit search --filter data_source
# ...
# 查询数据库
notion-toolkit database query <databaseId> \
  --filter '{"property":"Status","select":{"equals":"Active"}}' \
  --sorts '[{"property":"Created","direction":"descending"}]' \
  --page-size 10
# ...
# 获取页面
notion-toolkit page view <pageId>
# ...
# 读取块级内容
notion-toolkit block children <blockId>

写操作示例(需用户确认)

bash

# 创建页面(会提示用户确认)
notion-toolkit page create --parent-page <parentId> --title "新页面"
# ...
# 更新页面属性
notion-toolkit page update <pageId> --properties '{"Status":{"select":{"name":"Done"}}}'
# ...
# 追加块
notion-toolkit block append <blockId> \
  --children '[{"type":"paragraph","paragraph":{"rich_text":[{"text":{"content":"新段落"}}]}}]'
# ...
# 归档页面
notion-toolkit page archive <pageId>

筛选操作符参考

操作符	描述
equals	等于
does_not_equal	不等于
contains	包含
does_not_contain	不包含
starts_with	开头匹配
ends_with	结尾匹配
is_empty	为空
is_not_empty	非空
greater_than	大于
less_than	小于

块类型参考

块类型	描述
paragraph	段落
heading_1	一级标题
heading_2	二级标题
heading_3	三级标题
bulleted_list_item	无序列表项
numbered_list_item	有序列表项
to_do	待办事项
code	代码块
quote	引用
divider	分割线

最佳实践

1. 写操作必须用户确认:任何创建、更新、删除操作前,明确告知用户目标资源与影响
2. 使用最小权限连接:仅授予任务所需的页面与数据库访问权限
3. 指定具体连接ID:多账户场景下,务必指定--connection参数,避免误操作
4. 限定搜索范围:用--filter限定搜索类型(page/data_source),提升效率
5. 分页查询控制page_size:单次查询不超过100条,避免响应过大
6. 保留API版本头:所有请求必须携带Notion-Version: 2025-09-03头
7. 先查询后修改:修改前先page view确认目标,避免误改

安全与权限

• 访问范围限定在已授权连接的Notion账户内
• 所有写操作需用户明确批准:执行前必须确认目标(页面ID、数据库ID、块ID)
• 高风险操作需额外谨慎:
  • 删除页面或块(归档,但可能影响工作流)
  • 批量更新多个页面
  • 修改团队共享页面
• 权限边界:
  • 仅操作用户明确指定的资源
  • 使用最小权限连接
  • 不进行未经批准的批量操作

常见问题

Q1: 返回401 Unauthorized怎么办?

A: 检查API Key是否正确设置,运行notion-toolkit whoami验证鉴权状态。

Q2: 返回400 "Missing Notion connection"怎么办?

A: 需要先创建Notion连接:notion-toolkit connection create notion,然后在浏览器中完成OAuth授权。

Q3: 返回429 Too Many Requests怎么办?

A: 触发频率限制(免费版10 req/sec)。等待1秒后重试,或升级专业版提升限额。

Q4: 写操作被拒绝怎么办?

A: 写操作需要用户明确确认。Agent在执行前会询问用户:"是否要修改页面xxx?",用户确认后才会执行。

Q5: 如何获取数据源ID?

A: 先GET /databases/{id}获取数据库详情,响应中的data_sources数组包含数据源ID。

Q6: 创建数据库时属性被丢弃?

A: 在API 2025-09-03中,POST /databases仅接受title属性,其他属性会被静默丢弃。需要先创建数据库,再用PATCH /data_sources/{id}定义schema。

错误处理

错误场景(症状)	可能原因	解决方案
401 Unauthorized	API Key缺失或无效	检查环境变量,运行whoami验证
400 Missing connection	未创建Notion连接	执行connection create notion
404 Not Found	ID错误或资源未共享	确认ID正确,在Notion中共享给Integration
429 Rate limited	触发频率限制	等待1秒执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,或升级专业版
写操作失败	用户未确认	Agent明确询问用户后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
属性被丢弃	API版本限制	先创建再用PATCH定义schema

已知限制

本免费体验版限制以下高级功能:

• 多连接管理(同时管理>1个Notion账户)
• 批量操作(批量创建/更新/删除页面)
• Webhook订阅(页面变更事件推送)
• 自动分页(自动翻页获取全部结果)
• 高级筛选(复合条件、嵌套逻辑)
• API版本切换(仅支持2025-09-03)
• 自定义转换器(Jinja2模板)
• 团队协作与共享连接
• 审计日志与操作追踪

解锁全部功能请使用专业版:notion-api-toolkit-pro

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
• 操作系统: Windows / macOS / Linux
• Node.js: 16+(用于运行CLI工具)
• Python: 3.8+(可选,用于辅助脚本)

第三方依赖

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent平台内置LLM提供
notion-api-toolkit CLI	命令行工具	必需	npm install -g notion-api-toolkit
Notion账户	在线服务	必需	通过notion.so注册
curl	命令行工具	可选	操作系统自带
jq	JSON处理工具	推荐	通过包管理器安装

API Key 配置

• NOTION_TOOLKIT_API_KEY: 通过环境变量传入,用于API鉴权
• OAuth连接: 通过connection create命令创建,浏览器完成授权
• 安全建议: API Key禁止硬编码在脚本中,建议使用Secret管理服务
• 权限最小化: OAuth授权时仅勾选任务所需的权限范围

可用性分类

• 分类: MD+EXEC(纯Markdown指令,部分功能需exec命令行执行)
• 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent完成操作

输出格式

json

{
  "success": true,
  "data": {
    "result": "Notion API工具箱(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "notion apikit"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}