mcpField
N
notion

notion

github.com/acedatacloud生产力17207 次安装今天更新
代码仓库

关于 notion

这项 skill 指导 AI Agent 使用 `curl` 和 `jq` 调用 Notion API，提供搜索和读取工作区内容、查询数据库及创建或更新页面的示例，并提示共享权限与 API 版本要求。

主要功能

  1. 01验证 API 认证
  2. 02搜索工作区内容
  3. 03读取页面元数据和区块
  4. 04查询数据库
  5. 05追加内容并创建页面

适用场景

  1. 01查找已共享的工作区页面
  2. 02读取页面的完整内容
  3. 03筛选和排序数据库条目
  4. 04添加段落或创建数据库页面

安装

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

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

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

详细介绍

我们使用 curl + jq 调用 Notion API。用户的 OAuth bearer token 位于 $NOTION_TOKEN；每次调用都需要携带它以及 Notion-Version 标头。

Notion-Version 当前为 2022-06-28（最新稳定版本）。Notion 发布新版本时，请更新此标头。

用户的连接只能访问他们在授权时明确共享给集成的页面和数据库。如果搜索或读取页面没有返回结果，最可能的原因是“该页面从未共享给集成”——请向用户提示这一点。

操作指南

验证身份验证（始终先运行）
curl -sS https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  | jq '{id, name, type, bot: (.bot != null)}'
搜索工作区
curl -sS https://api.notion.com/v1/search \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"query": "Q1 budget", "page_size": 10}' \
  | jq '.results[] | {id, type: .object, url, title: (.properties.title // .properties.Name)?.title?[0]?.plain_text // .child_page?.title}'
读取页面（仅元数据）
curl -sS "https://api.notion.com/v1/pages/PAGE_ID" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28"
读取页面的完整内容
curl -sS "https://api.notion.com/v1/blocks/PAGE_ID/children?page_size=100" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  | jq '.results[] | {type, content: (.[.type] // {})}'
向页面追加段落
curl -sS -X PATCH "https://api.notion.com/v1/blocks/PAGE_ID/children" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc --arg text "Appended via the assistant." '
    {children: [{
      object: "block",
      type: "paragraph",
      paragraph: {rich_text: [{type:"text", text:{content:$text}}]}
    }]}')"
查询数据库
curl -sS -X POST "https://api.notion.com/v1/databases/DATABASE_ID/query" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Open"}},
    "sorts":  [{"property": "Updated", "direction": "descending"}],
    "page_size": 25
  }'
在数据库中创建页面
curl -sS -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc \
        --arg db "DATABASE_ID" \
        --arg title "New entry" \
        '{
          parent: {database_id: $db},
          properties: {
            Name:   {title: [{text: {content: $title}}]},
            Status: {select: {name: "Open"}}
          }
        }')"

注意事项

  • Notion 使用基于游标的分页：添加 start_cursor=$cursor 进行分页，并使用每个响应中的 next_cursor。当 has_more 为 false 时停止。
  • 大多数写入失败（400/404）都源于属性类型不匹配——例如，发送 {"select": "Open"} 而不是 {"select": {"name": "Open"}}。如果不确定，请通过 GET /v1/databases/<id> 读取一次数据库架构。

记录输出

成功发布并获得有效结果 URL 后，请调用内置的 publish_artifact 工具一次，让用户能够在 My Outputs 中追踪此交付内容：

publish_artifact(kind="document", channel="notion", title="<title>", url="<the REAL returned URL>", status="delivered")

使用实际返回的 URL——切勿伪造。每个已发布的项目只调用一次，并且仅在确认交付后调用；如果发布失败，请跳过调用（或使用 status="failed"）。 请参阅 _shared/artifacts.md。

评论

支持 Markdown