mcpField
N
notion

notion

github.com/letta-ai生产力152114 次安装4 周前更新
代码仓库

关于 notion

notion 技能指导通过 Notion API 创建、读取和更新页面、数据源及内容块，面向需要在自动化流程中操作 Notion 的用户。它涵盖新版 API 的数据源端点和常见操作。

主要功能

  1. 01搜索页面和数据源
  2. 02读取页面与内容块
  3. 03创建页面和数据源
  4. 04更新页面属性与内容块
  5. 05说明 API 认证及版本差异

适用场景

  1. 01查找并读取 Notion 页面
  2. 02向数据库添加页面条目
  3. 03更新页面状态或属性
  4. 04向页面追加文本内容

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/letta-ai/skills --skill notion

安装后在 Claude Code 中输入/notion确认已加载。

附带文件assets/notion-small.svgLICENSE

详细介绍

notion

使用 Notion API 创建、读取和更新页面、数据源（数据库）及块。

设置

  1. 在 https://notion.so/my-integrations 创建集成
  2. 复制 API 密钥（以 ntn_ 或 secret_ 开头）
  3. 保存：
mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key
  1. 将目标页面／数据库共享给你的集成（点击“...” →“Connect to”→ 选择你的集成名称）

API 基础知识

所有请求都需要：

NOTION_KEY=$(cat ~/.config/notion/api_key)
curl -X GET "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

注意： 必须提供 Notion-Version 标头。此技能使用 2025-09-03（最新版本）。在此版本中，API 将数据库称为“数据源”。

常见操作

搜索页面和数据源：

curl -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "page title"}'

获取页面：

curl "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

获取页面内容（块）：

curl "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

在数据源中创建页面：

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "xxx"},
    "properties": {
      "Name": {"title": [{"text": {"content": "New Item"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }'

查询数据源（数据库）：

curl -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Active"}},
    "sorts": [{"property": "Date", "direction": "descending"}]
  }'

创建数据源（数据库）：

curl -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "title": [{"text": {"content": "My Database"}}],
    "properties": {
      "Name": {"title": {}},
      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
      "Date": {"date": {}}
    }
  }'

更新页面属性：

curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'

向页面添加块：

curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}
    ]
  }'

属性类型

数据库条目常用的属性格式：

  • 标题： {"title": [{"text": {"content": "..."}}]}
  • 富文本： {"rich_text": [{"text": {"content": "..."}}]}
  • 单选： {"select": {"name": "Option"}}
  • 多选： {"multi_select": [{"name": "A"}, {"name": "B"}]}
  • 日期： {"date": {"start": "2024-01-15", "end": "2024-01-16"}}
  • 复选框： {"checkbox": true}
  • 数字： {"number": 42}
  • URL： {"url": "https://..."}
  • 电子邮件： {"email": "[email protected]"}
  • 关联： {"relation": [{"id": "page_id"}]}

2025-09-03 版本的主要变化

  • 数据库 → 数据源： 查询和检索请使用 /data_sources/ 端点
  • 两个 ID： 每个数据库现在都有 database_id 和 data_source_id
    • 创建页面时使用 database_id（parent: {"database_id": "..."}）
    • 查询时使用 data_source_id（POST /v1/data_sources/{id}/query）
  • 搜索结果： 数据库以 "object": "data_source" 的形式返回，并包含其 data_source_id
  • 响应中的父级信息： 页面会在 parent.database_id 旁显示 parent.data_source_id
  • 查找 data_source_id： 搜索数据库，或调用 GET /v1/data_sources/{data_source_id}

注意事项

  • 页面／数据库 ID 是 UUID（带或不带连字符）
  • API 无法设置数据库视图筛选条件，此操作只能在 UI 中完成
  • 速率限制：平均约为每秒 3 个请求；触发限制时会返回 429 rate_limited，并附带 Retry-After
  • 追加块子项：每个请求最多 100 个子项；单次追加请求最多支持两层嵌套
  • 负载大小限制：最多 1000 个块元素，整体不超过 500KB
  • 创建数据源并将其嵌入页面时，请使用 is_inline: true

评论

支持 Markdown