mcpField
N
notion

notion

github.com/openhandsProductivity17582 installsUpdated today
Repository

About notion

A Notion skill for working with pages and databases through authenticated MCP tools or the Notion REST API. It provides API examples and guidance on credentials, sharing, and Windows PowerShell equivalents.

Key features

  1. 01Prefer authenticated Notion MCP tools
  2. 02Search for pages by title
  3. 03Create pages and append blocks
  4. 04Direct REST API request examples
  5. 05Windows PowerShell equivalents

Use cases

  1. 01Finding a Notion page by title
  2. 02Creating pages under a parent page
  3. 03Appending content to an existing page

MCP support

When authenticated Notion MCP tools are available, the skill recommends using them before direct REST API calls. It also explains using the REST API when MCP is unavailable or raw API access is needed.

Install

Copy the command and run it in a terminal.

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

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

Bundled files

References and scripts installed along with SKILL.md.

README.md
.plugin/
plugin.json
references/
windows.md

Details

From the project README

Notion

Windows PowerShell equivalents for the repeated Notion REST curl, environment-variable, and JSON-body snippets are in references/windows.md.

If authenticated Notion MCP tools are available in the environment, use them first. MCP tools do not require passing `NOTION_INTEGRATION_KEY` as a tool argument; authentication is handled by the configured MCP integration.

Use the direct Notion REST API examples below only when MCP is unavailable or when you explicitly need raw API/curl access. For that direct-API path, first check whether the required environment variable is set:

[ -n "$NOTION_INTEGRATION_KEY" ] && echo "NOTION_INTEGRATION_KEY is set" || echo "NOTION_INTEGRATION_KEY is NOT set"

If it’s missing and you need the direct API path, ask the user to provide it (or connect a Notion integration) before proceeding:

  • NOTION_INTEGRATION_KEY: Notion integration secret (starts with ntn_...)

Whether you use MCP or the direct API, also confirm the configured integration has been shared with the target page/database in Notion.

Base headers for direct API calls

-H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
-H "Notion-Version: 2022-06-28" \
-H "Content-Type: application/json"

Find a page (search)

Use Notion’s search endpoint to find a page by title.

curl -s https://api.notion.com/v1/search \
  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "OpenHands Wiki",
    "page_size": 10
  }' | jq .

Create a page under a parent page

PARENT_PAGE_ID="<parent_page_id>"

curl -s https://api.notion.com/v1/pages \
  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "page_id", "page_id": "'"${PARENT_PAGE_ID}"'"},
    "properties": {
      "title": {
        "title": [{"type": "text", "text": {"content": "My new page"}}]
      }
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Hello from OpenHands."}}]
        }
      }
    ]
  }' | jq .

Append blocks to an existing page

Use the page’s block id (same as page id) to append children.

PAGE_ID="<page_id>"

curl -s -X PATCH "https://api.notion.com/v1/blocks/${PAGE_ID}/children" \
  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {"rich_text": [{"type": "text", "text": {"content": "Appended section"}}]}
      }
    ]
  }' | jq .

Tips / gotchas

  • Sharing is required: even with a valid key, the integration can’t see a page/database until it has been shared with the integration in the Notion UI.
  • Rate limits: keep requests small; for large pages, create the page first and then append blocks in batches.
  • IDs format: Notion IDs may be returned with dashes; both dashed and non-dashed forms typically work in API calls.

Documentation

Comments

Markdown supported