slug: notion name: "notion" version: 1.0.2 displayName: "Notion笔记工具" summary: '"Notion API创建管理页面/数据库/块。Notion API for creating and managing pages, databases, and blocks。核心能力:"' summary_zh: '"Notion API创建管理页面/数据库/块。Notion API for creating and managing pages, databases, and blocks。核心能力:"' license: "MIT" description: [''商业工具领域的专业化AI辅助工具'']。"Notion API创建管理页面/数据库/块。Notion API for creating。Use when 需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于实时流数据处理。适用于独立开发者、企业团队和自动化工作流场景。支持中文交互，无需复杂配置即开即用。 and managing pages, databases, and blocks。核心能力:"。"Notion笔记工具"工具。支持自动化配置和灵活的参数设置，适适用于不同工作场景，改善操作效率。' 适用场景:

• 日程管理、效率提升、团队协作
• 独立开发者与一人公司效率提升
• 自动化工作流与智能决策辅助 tags:
• Productivity
• 工具
• 效率
• 写作
• notion
• content
• text
• json
• api tools:
• read
• exec
• glob
• grep homepage: '""' category: '"Automation"' homepage: "" pricing_tier: "L2-标准级"

功能说明: 本技能涵盖 中文交互、化工作流场景 等核心能力。

Notion

专业版增强能力

功能能力

• 页面管理：通过Notion API创建、读取、更新、删除页面，支持设置页面属性、标题、图标、封面
• 数据库操作：创建数据库、查询数据库条目、按属性筛选与排序、批量插入与更新记录
• 块内容编辑：向页面追加文本块、标题块、列表块、代码块、引用块、分割线等Block类型
• 属性类型支持：处理标题、文本、数字、选择(Select)、多选(Multi-select)、日期、人员、文件、复选框、URL、邮箱、公式、关联(Relation)等属性
• 搜索功能：按标题和内容搜索用户有权限访问的页面和数据库
• 批量操作：支持单次请求批量创建最多100个块、批量查询数据库条目（分页获取）

适用范围

不适用于：Notion页面实时协作编辑、Notion评论管理、Notion工作区设置管理、文件上传（需配合files API）

使用指南

1. 确认运行环境满足依赖说明中的要求，已配置Notion Integration Token
2. 在Notion中将目标页面/数据库与Integration共享（添加连接）
3. 确定操作类型：创建页面、查询数据库、追加块内容等
4. 构造API请求参数（页面ID、数据库ID、块内容JSON）
5. 执行操作并检查返回的页面ID或块ID
6. 验证结果：在Notion中打开对应页面确认内容正确

输入定义

结果格式

{
  "success": true,
  "data": {
    "page": {
      "id": "page-uuid-string",
      "url": "https://notion.so/page-uuid-string",
      "properties": {
        "Name": {
          "title": [{"text": {"content": "新任务"}}]
        },
        "Status": {
          "select": {"name": "进行中", "color": "blue"}
        }
      }
    },
    "metadata": {
      "template_used": "reviewer",
      "operation": "create_page",
      "blocks_created": 3,
      "style": "专业"
    }
  },
  "error": null
}

输出模板参考: assets/output.json

详细使用示例

示例1：创建数据库条目

{
  "operation": "create_page",
  "database_id": "abc123def456",
  "content": {
    "Name": {"title": [{"text": {"content": "修复登录Bug"}}]},
    "Status": {"select": {"name": "待处理"}},
    "Priority": {"select": {"name": "高"}},
    "Due Date": {"date": {"start": "2024-01-20"}},
    "Tags": {"multi_select": [{"name": "前端"}, {"name": "紧急"}]}
  }
}

示例2：查询数据库并筛选

{
  "operation": "query_db",
  "database_id": "abc123def456",
  "content": {
    "filter": {
      "and": [
        {"property": "Status", "select": {"equals": "待处理"}},
        {"property": "Priority", "select": {"equals": "高"}}
      ]
    },
    "sorts": [
      {"property": "Due Date", "direction": "ascending"}
    ],
    "page_size": 10
  }
}

示例3：向页面追加内容块

{
  "operation": "append_blocks",
  "page_id": "page-uuid-string",
  "content": {
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {"rich_text": [{"type": "text", "text": {"content": "会议纪要"}}]}
      },
      {
        "object": "block",
        "type": "bulleted_list_item",
        "bulleted_list_item": {"rich_text": [{"type": "text", "text": {"content": "讨论了Q1路线图"}}]}
      },
      {
        "object": "block",
        "type": "to_do",
        "to_do": {"rich_text": [{"type": "text", "text": {"content": "完成API文档"}}], "checked": false}
      },
      {
        "object": "block",
        "type": "code",
        "code": {"rich_text": [{"type": "text", "text": {"content": "npm install"}}], "language": "bash"}
      }
    ]
  }
}

示例4：搜索页面

{
  "operation": "search",
  "content": {
    "query": "项目计划",
    "filter": {"property": "object", "value": "page"},
    "page_size": 5
  }
}

支持的块类型

优选实践

Integration配置

• 在 https://notion.so/my-integrations 创建Internal Integration获取Token
• Token格式为 secret_xxxxxxxxxxxx，以环境变量 NOTION_TOKEN 存储
• 必须在目标页面/数据库点击"..." → "Connections" → 添加Integration才能访问

数据库属性映射

• 标题属性使用 title 类型，每个数据库只能有一个标题属性
• Select/Multi-select的选项需预先在Notion中创建，或通过API自动创建
• 日期属性使用ISO 8601格式：{"start": "2024-01-20", "end": "2024-01-21"}
• Relation属性需提供目标数据库ID和关联页面ID

批量操作

• 单次 append_blocks 最多创建100个块，超出需分批请求
• query_db 默认返回10条，最大100条，通过 start_cursor 分页获取
• 避免频繁API调用，Notion API限制每秒3次请求

安装与配置

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
• 操作系统: Windows / macOS / Linux

依赖说明(补充)

API Key 配置

可用性分类

• 分类: MD+execute()
• 说明: 基于Markdown的AI Skill,

API Key配置方式:

export NOTION_TOKEN="secret_your_integration_token_here"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

问答速查

Q1: 如何开始使用Notion API？

A: 首先在 https://notion.so/my-integrations 创建Internal Integration，获取Token（secret_ 开头）。然后在Notion中打开要操作的页面或数据库，点击右上角"..." → "Connections" → 搜索并添加你的Integration。最后将Token设置为环境变量 NOTION_TOKEN，即可通过 create_page、query_db、append_blocks 等操作管理Notion内容。

Q2: 为什么API返回"object not found"错误？

A: 此错误表示Integration没有访问目标资源的权限。Notion的权限模型要求每个页面/数据库单独授权。解决方法：打开目标页面 → "..." → "Connections" → 添加Integration。注意：如果页面在子页面中，需要对父页面授权，子页面会继承权限。

Q3: 如何处理富文本格式（加粗、斜体、链接）？

A: Notion的富文本通过 rich_text 数组实现，每个元素可指定不同样式。例如加粗文本：{"type": "text", "text": {"content": "重要"}, "annotations": {"bold": true}}。链接文本：{"type": "text", "text": {"content": "点击这里", "link": {"url": "https://example.com"}}}。一个 rich_text 数组可包含多个不同样式的文本段。

Q4: 数据库查询的筛选语法是怎样的？

A: 筛选使用 filter 对象，支持 and/or 组合条件。单属性筛选：{"property": "Status", "select": {"equals": "进行中"}}。多属性组合：{"and": [{"property": "Status", "select": {"equals": "进行中"}}, {"property": "Priority", "select": {"equals": "高"}}]}。每种属性类型有不同的筛选操作符：select支持 equals/does_not_equal，date支持 before/after/on_or_before，text支持 contains/starts_with。

错误管理机制

注意事项

• 需要API Key，无Key环境无法使用
• 不支持Notion评论API（comments）
• 不支持文件上传到Notion（需使用files API单独处理）
• 不支持页面导出为PDF/Markdown（需使用Notion内置导出功能）
• API请求限制为每秒3次，大批量操作需分批并加延迟
• 块内容单次最多追加100个块，超出需分批请求

创新亮点

效率提升量化分析

差异化对比

核心痛点解决

问题处理指引

安全实践准则

1. 确保Notion API Token安全，避免泄露给未授权人员。
2. 定期检查API调用日志，及时发现异常调用行为。
3. 对敏感数据进行加密处理，防止数据泄露。
4. 使用HTTPS协议进行API调用，确保数据传输安全。
5. 限制API调用频率，防止API滥用。

安全风险防范

异常恢复方案

针对Notion笔记工具使用中可能遇到的常见问题,提供以下排查方案:

Notion笔记工具通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块