notion-cli

An agent-first Notion CLI and MCP server, purpose-built for the Notion API 2025-09-03+ data-source model. Three-tier MCP privilege model: read-only default, runtime writes, admin lifecycle.

Features

• Three-tier MCP — read-only default (7 tools), --allow-write runtime CRUD (13 tools), --allow-admin lifecycle ops (18 tools)
• Admin lifecycle — db create, db update (incl. parent move via PATCH), ds update (single-delta: add/remove/rename-property + add-option + bulk), ds add-relation (dual/single/self), page move via dedicated /move endpoint
• Bot self-identity — users me (MCP users_me RO tool) returns the bot's own identity without enumerating workspace PII
• Universal --json <body> — zero-translation agent path on all 7 mutation commands; stdin / @file / literal modes; mutually exclusive with bespoke flags (exit 2 on mixed)
• NDJSON streaming — --stream / --format=jsonl on 5 paginated commands (ds query, block list, search, users list, comments list) with explicit item / end / error frames
• --check-request --cost — API call count + rate-limit window preview without contacting Notion
• Field-mask page reads — page get --properties <ids> (Notion filter_properties) and page get-property <page> <prop-id> for paginated relation/rollup/people properties
• Observability — per-request UUID v7 request_id propagated to audit log; tracing subscriber; OTel exporter behind cargo feature otel
• GET response cache — opt-in via NOTION_CLI_CACHE_TTL; writes auto-invalidate by entity
• Idempotency-Key — auto-generated on POST/PATCH; MCP callers can override via idempotency_key param
• Token chain — env → file → keychain (macOS) → exec; stderr warning on shadowing
• CLI-only surfaces — users list/get, comments list/create (not exposed over MCP; privacy / scope)
• Page body & icon/cover — page create --children for one-shot page + body; page update --icon/--cover tristate (set / clear / leave)
• CLI + MCP — same tool surface accessible via shell commands or as an MCP stdio server
• Agent-friendly output — responses wrapped in an untrusted-source envelope with trust metadata; --raw for clean piping
• Rate limiting — built-in 3 req/s token bucket with 429 Retry-After retry (configurable)
• Response size cap — 10 MiB streaming limit prevents OOM on large payloads
• Schema introspection — notion-cli schema <type> emits JSON Schema for 22 property types, 12 block types, and more
• Two-sink audit log — NOTION_CLI_AUDIT_LOG for runtime writes + NOTION_CLI_ADMIN_LOG for admin ops; each entry carries a privilege field
• Destructive safety gate — TTY-aware prompt on interactive shells; non-TTY requires --yes. MCP admin destructive ops gated by confirm=true + NOTION_CLI_ADMIN_CONFIRMED=1 env (two-factor)
• Actionable error hints — common Notion validation errors get one-line remediation suggestions
• Structured exit codes — stable numeric codes (0/2/3/4/10/64/65/74) for scripting and CI
• Newtype ID validation — accepts 32-hex, dashed UUID, or full Notion URLs; rejects homoglyphs and control characters
• --check-request — validate and preview request payloads locally without contacting Notion

Quick Start

# Install
cargo install --git https://github.com/0xarkstar/notion-cli

# Set your integration token
export NOTION_TOKEN='ntn_...'

# Search across your workspace
notion-cli search 'meeting notes'

# Query a data source with filters
notion-cli ds query <data-source-id> \
  --filter '{"property":"Done","checkbox":{"equals":false}}'

Installation

crates.io

cargo install notion-cli-mcp

(The crate is published as notion-cli-mcp; the installed binary is notion-cli.)

Prebuilt binaries (macOS / Linux, aarch64 + x86_64)

curl -LsSf https://github.com/0xarkstar/notion-cli/releases/latest/download/notion-cli-installer.sh | sh

Homebrew

brew install 0xarkstar/tap/notion-cli

ClawHub (for Hermes / OpenClaw agents)

Published as notion-cli-mcp on ClawHub:

clawhub install 0xarkstar/notion-cli-mcp

The skill describes the full tool surface and example payloads for agent consumption.

From source

cargo install --git https://github.com/0xarkstar/notion-cli

Requires Rust 1.85+. Run notion-cli --version to verify.

Usage

Pages

# Retrieve a page (accepts IDs or full Notion URLs)
notion-cli page get https://notion.so/My-Page-abcdef0123456789abcdef0123456789

# Create a page under a data source
notion-cli page create \
  --parent-data-source <data-source-id> \
  --properties '{
    "Name": {"type":"title","title":[{"type":"text","text":{"content":"New page"}}]},
    "Status": {"type":"status","status":{"name":"In Progress"}}
  }'

# Update properties
notion-cli page update <page-id> \
  --properties '{"Status":{"type":"status","status":{"name":"Done"}}}'

# Archive
notion-cli page archive <page-id>

Data Sources

# Retrieve schema and metadata
notion-cli ds get <data-source-id>

# Query with filter, sort, and pagination
notion-cli ds query <data-source-id> \
  --filter '{"property":"Priority","select":{"equals":"High"}}' \
  --sorts '[{"property":"Due","direction":"ascending"}]' \
  --page-size 25

# Create a new data source in a database container
notion-cli ds create \
  --parent <database-id> \
  --title 'Tasks' \
  --properties '{"Name":{"title":{}},"Done":{"checkbox":{}}}'

Search & Introspection

# Full-text search (filter by object type)
notion-cli search 'onboarding' \
  --filter '{"property":"object","value":"page"}'

# Retrieve a database container (lists its data sources)
notion-cli db get <database-id>

# Print JSON Schema for property values (all 22 types)
notion-cli schema property-value --pretty

Request Validation

Preview what would be sent without making an API call:

notion-cli --check-request --pretty page create \
  --parent-data-source <id> \
  --properties '{"Name":{"type":"title","title":[{"type":"text","text":{"content":"test"}}]}}'

No token required for --check-request.

MCP Server

Start as an MCP stdio server for agent integration:

# Read-only (4 tools: get_page, get_data_source, query_data_source, search)
notion-cli mcp

# Full access (7 tools: above + create_page, update_page, create_data_source)
notion-cli mcp --allow-write

# With audit logging
notion-cli mcp --allow-write --audit-log ./notion-audit.jsonl

Agent configuration example

mcp_servers:
  notion:
    command: notion-cli
    args: [mcp, --allow-write, --audit-log, /var/log/notion-audit.jsonl]
    env:
      NOTION_TOKEN: ntn_xxx
    enabled: true

Output Format

Responses are wrapped in a trust-demarcation envelope by default:

{
  "source": "notion",
  "trust": "untrusted",
  "api_version": "2026-03-11",
  "content": { ... }
}

This signals to consuming agents that content originates from an external source and should be treated as data, not instructions. Use --raw to strip the envelope, and --pretty for indented output.

Configuration

Create an integration at notion.so/my-integrations, then share target pages/databases with it via the Connections menu.

Exit Codes

Development

cargo test              # 130 tests
cargo clippy --all-targets -- -D warnings
cargo llvm-cov --all-targets --summary-only   # 80%+ line coverage
cargo audit             # 0 advisories

# Live smoke test against a real workspace
export NOTION_TOKEN='ntn_...'
cargo run --example smoke -- <database-url>

Roadmap

• Block CRUD (page body / children)
• NDJSON streaming for paginated queries
• --fields response field masks
• YAML configuration file
• Multi-platform binaries via cargo-dist / Homebrew

License

MIT