mcpField
N
notion

notion

github.com/acedatacloudProductivity17207 installsUpdated today
Repository

About notion

A skill for AI agents that use the Notion API with `curl` and `jq`. It includes examples for searching and reading workspace content, querying databases, and creating or updating pages, while noting integration sharing and API version requirements.

Key features

  1. 01Verify API authentication
  2. 02Search workspace content
  3. 03Read page metadata and blocks
  4. 04Query databases
  5. 05Append content and create pages

Use cases

  1. 01Find shared pages in a workspace
  2. 02Read a page's full content
  3. 03Filter and sort database entries
  4. 04Add a paragraph or create a database page

Install

Copy the command and run it in a terminal.

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

After installing, type/notionin Claude Code to confirm it loaded.

Details

From the project README

We drive the Notion API with curl + jq. The user's OAuth bearer token is in $NOTION_TOKEN; every call needs it plus the Notion-Version header.

Notion-Version is currently 2022-06-28 (the most recent stable). Bump this header when Notion ships a new version.

The user's connection only sees the pages and databases they explicitly shared with the integration when they authorized. If a search or page read returns nothing, the most likely cause is "the page was never shared with the integration" — surface that hint to the user.

Recipes

Verify auth (always run first)
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)}'
Search the workspace
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}'
Read a page (metadata only)
curl -sS "https://api.notion.com/v1/pages/PAGE_ID" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28"
Read a page's full content
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] // {})}'
Append a paragraph to a page
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}}]}
    }]}')"
Query a database
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
  }'
Create a page in a database
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"}}
          }
        }')"

Notes

  • Notion's pagination is cursor-based: append start_cursor=$cursor to paginate, using the next_cursor from each response. Stop when has_more is false.
  • Most write failures (400/404) come from a property type mismatch — e.g. sending {"select": "Open"} instead of {"select": {"name": "Open"}}. Read the database schema once via GET /v1/databases/<id> if unsure.

Record the output

After you successfully publish and obtain the live result URL, call the built-in publish_artifact tool ONCE so the user can track this deliverable in My Outputs:

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

Use the real returned URL — never fabricate one. Call it once per published item, only after delivery is confirmed; skip it (or use status="failed") if publishing failed. See _shared/artifacts.md.

Comments

Markdown supported