How do I install Notion CLI?

Run git clone https://github.com/0xarkstar/notion-cli, then add the server to your MCP client's configuration. Conduid has recorded 0 installs, so the command is known to work with current clients.

Is Notion CLI safe to use with an AI agent?

Its trust score is 39 out of 100 (low). Conduid hasn't run static security checks on this repository yet, so review the source yourself before granting it credentials. It has no ConduID identity yet, so agent calls to it are not receipted.

Is Notion CLI still maintained?

Conduid hasn't recorded a commit date for this repository yet. Check the repository directly for recent activity.

About Notion CLI

Notion CLI is an MCP server in the Productivity category: cLI for Notion using the Model Context Protocol (MCP). It has been installed 0 times through Conduid.

The repository has 36 stars and 0 forks.

Install

Clone

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

This server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.

Ask AI

✦

Ask AI about Notion CLI

I know everything about Notion CLI. Ask me about installation, configuration, usage, or troubleshooting.

Security checks

·README presentNot checked yet.
·License declaredNot checked yet.
·Tests presentNot checked yet.
·Dependencies pinnedNot checked yet.
·No dynamic code executionNot checked yet.
·Scoped permissionsNot checked yet.

README

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

Setting	Source	Description
`NOTION_TOKEN`	env / `--token`	Integration token (`ntn_...`)
`NOTION_CLI_AUDIT_LOG`	env / `--audit-log`	Path for write-operation JSONL audit log

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

Exit Codes

Code	Meaning
0	Success
2	Validation error
3	API error
4	Rate-limited
10	Auth / config error
64	Usage error
65	JSON parse error
74	I/O error

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

Read full README

README mirrored from the source repository 2 hours ago. The original is authoritative.

About Notion CLI

Install

Ask AI

Security checks

README

notion-cli

Features

Quick Start

Installation

crates.io

Prebuilt binaries (macOS / Linux, aarch64 + x86_64)

Homebrew

ClawHub (for Hermes / OpenClaw agents)

From source

Usage

Pages

Data Sources

Search & Introspection

Request Validation

MCP Server

Agent configuration example

Output Format

Configuration

Exit Codes

Development

Roadmap

License

Alternatives to Notion CLI

Dotnet Outdated

Bank API

Cuga Agent

Sampleproject

Atlassian MCP Server

Minthcm

About Notion CLI