mcpField
N
notion

notion

github.com/acedatacloud生産性17207 回インストール今日更新
リポジトリ

notion について

AI エージェントが `curl` と `jq` で Notion API を使うためのスキルです。ワークスペースの検索・読み取り、データベース照会、ページの作成・更新例に加え、共有権限と API バージョンの要件も示します。

主な機能

  1. 01API 認証の確認
  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を入力して読み込まれたか確認します。

詳細

Notion API を curl + jq で操作します。ユーザーの OAuth ベアラートークンは $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 のページネーションはカーソルベースです。ページを続けて取得するには、各レスポンスの next_cursor を使って start_cursor=$cursor を追加します。has_more が false になったら終了します。
  • 書き込みの失敗（400/404）の多くは、プロパティ型の不一致が原因です。たとえば、{"select": {"name": "Open"}} ではなく {"select": "Open"} を送信している場合です。不明な場合は、GET /v1/databases/<id> を使ってデータベースのスキーマを一度読み取ってください。

出力を記録する

公開が成功し、公開結果の URL を取得したら、組み込みの publish_artifact ツールを 1 回だけ呼び出して、ユーザーがこの成果物を My Outputs で確認できるようにします。

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

実際に返された URL を使用し、決して捏造しないでください。公開済みの項目ごとに、配信が確認された後で 1 回だけ呼び出します。公開に失敗した場合は呼び出さないか、status="failed" を使用してください。_shared/artifacts.md を参照してください。

コメント

Markdown 対応