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:
2. Go to https://www.notion.so/my-integrations
3. Click "New integration"
4. Give it a name (e.g., "OpenClaw")

5. Copy the "Internal Integration Token"

6. Set environment variable: bash export NOTION_TOKEN=your_integration_token_here

7. Share pages/databases with your integration:

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

Usage

All commands use the pattern:

uv run {baseDir}/scripts/notion.py <command> [options]

Page Operations

Create a page:

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

Get a page:

uv run {baseDir}/scripts/notion.py page get <page_id>

Update a page:

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

Delete (archive) a page:

uv run {baseDir}/scripts/notion.py page delete <page_id>

List child pages:

uv run {baseDir}/scripts/notion.py page list --parent <page_id>

Database Operations

Query a database:

# Simple query
uv run {baseDir}/scripts/notion.py db query <db_id>

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

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

Add page to database:

uv run {baseDir}/scripts/notion.py db add <db_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 <page_id> 
  --type paragraph 
  --text "This is a paragraph"

Append to-do:

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

Append heading:

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

Append code block:

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

List child blocks:

uv run {baseDir}/scripts/notion.py block children <block_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 <workspace_root_id> 
  --title "Meeting Notes - 2026-03-10" 
  --content "Attendees: Team"

Add task to project database:

uv run {baseDir}/scripts/notion.py db add <project_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 <parent> --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