Notion Agent

OpenClaw skill for managing Notion workspaces via AI agents. Provides CLI commands for pages, databases, blocks, and search.

Setup

1. Create a Notion Integration:

   • Go to https://www.notion.so/my-integrations
   • Click "New integration"
   • Give it a name (e.g., "OpenClaw")
   • Copy the "Internal Integration Token"

2. Set environment variable:

   export NOTION_TOKEN=your_integration_token_here
   

3. Share pages/databases with your integration:

   • Open the page or database in Notion
   • Click "..." → "Add connections"
   • Select your integration

Usage

All commands use the pattern:

uv run {baseDir}/scripts/notion.py \x3Ccommand> [options]

Page Operations

Create a page:

uv run {baseDir}/scripts/notion.py page create \
  --parent \x3Cparent_page_id> \
  --title "My New Page" \
  --content "Initial paragraph content"

Get a page:

uv run {baseDir}/scripts/notion.py page get \x3Cpage_id>

Update a page:

uv run {baseDir}/scripts/notion.py page update \x3Cpage_id> \
  --title "Updated Title"

Delete (archive) a page:

uv run {baseDir}/scripts/notion.py page delete \x3Cpage_id>

List child pages:

uv run {baseDir}/scripts/notion.py page list --parent \x3Cpage_id>

Database Operations

Query a database:

# Simple query
uv run {baseDir}/scripts/notion.py db query \x3Cdb_id>

# With filter
uv run {baseDir}/scripts/notion.py db query \x3Cdb_id> --filter Name=Todo

# With sort
uv run {baseDir}/scripts/notion.py db query \x3Cdb_id> --sort Priority:desc

Add page to database:

uv run {baseDir}/scripts/notion.py db add \x3Cdb_id> \
  --props '{"Name":{"title":[{"text":{"content":"Task"}}]},"Status":{"select":{"name":"Done"}}}'

List all databases:

uv run {baseDir}/scripts/notion.py db list

Block Operations

Append paragraph:

uv run {baseDir}/scripts/notion.py block append \x3Cpage_id> \
  --type paragraph \
  --text "This is a paragraph"

Append to-do:

uv run {baseDir}/scripts/notion.py block append \x3Cpage_id> \
  --type todo \
  --text "Task to complete" \
  --checked

Append heading:

uv run {baseDir}/scripts/notion.py block append \x3Cpage_id> \
  --type heading1 \
  --text "Section Title"

Append code block:

uv run {baseDir}/scripts/notion.py block append \x3Cpage_id> \
  --type code \
  --text "print('Hello, World!')" \
  --language python

List child blocks:

uv run {baseDir}/scripts/notion.py block children \x3Cblock_id>

Search

Search workspace:

# Search all
uv run {baseDir}/scripts/notion.py search "project plan"

# Search only pages
uv run {baseDir}/scripts/notion.py search "meeting notes" --type page

# Search only databases
uv run {baseDir}/scripts/notion.py search "tasks" --type database

Error Handling

The CLI handles common errors:

• NOTION_TOKEN not set — Set the environment variable
• Invalid NOTION_TOKEN — Check your integration token
• Resource not found — Page/database doesn't exist or integration lacks access
• Permission denied — Share the resource with your integration

API Reference

• Base URL: https://api.notion.com/v1
• API Version: 2022-06-28
• Authentication: Bearer token via NOTION_TOKEN

Limitations

• Uses requests library only (no Notion SDK)
• Simple filter/sort syntax (single property)
• Rich text limited to plain text content
• Database properties must be formatted as JSON

Examples for AI Agents

Create a meeting notes page:

uv run {baseDir}/scripts/notion.py page create \
  --parent \x3Cworkspace_root_id> \
  --title "Meeting Notes - 2026-03-10" \
  --content "Attendees: Team"

Add task to project database:

uv run {baseDir}/scripts/notion.py db add \x3Cproject_db_id> \
  --props '{"Name":{"title":[{"text":{"content":"Fix bug #123"}}]},"Status":{"select":{"name":"In Progress"}},"Priority":{"select":{"name":"High"}}}'

Build a structured page:

PAGE_ID=$(uv run {baseDir}/scripts/notion.py page create --parent \x3Cparent> --title "Report" | jq -r .id)
uv run {baseDir}/scripts/notion.py block append $PAGE_ID --type heading1 --text "Executive Summary"
uv run {baseDir}/scripts/notion.py block append $PAGE_ID --type paragraph --text "Key findings..."
uv run {baseDir}/scripts/notion.py block append $PAGE_ID --type heading2 --text "Details"
uv run {baseDir}/scripts/notion.py block append $PAGE_ID --type todo --text "Review findings"

Help

uv run {baseDir}/scripts/notion.py --help
uv run {baseDir}/scripts/notion.py page --help
uv run {baseDir}/scripts/notion.py db --help
uv run {baseDir}/scripts/notion.py block --help