notion-cli-mcp
Notion via notion-cli — a Rust CLI + MCP server for Notion API 2025-09-03+. Three-tier agent integration (read-only default, opt-in runtime writes, opt-in admin lifecycle) with rate limiting, response-size cap, untrusted-source output envelope, per-tier JSONL audit logs, and --check-request dry-runs. Supports the new data-source model, 22 property types, 12 block types, admin schema mutation, relation wiring, dedicated page-move endpoint, db update, and users me (v0.4).
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/0xarkstar/notion-cli-mcpnotion-cli-mcp
Agent-first Notion access via the notion-cli binary (Rust, MIT). A single tool that serves both a shell CLI and an MCP stdio server with an explicit three-tier privilege model.
Three-tier privilege model
notion-cli mcp exposes three mutually exclusive tiers, selected by flag:
| Flag | Tier | Tool count | Intended audience |
|---|---|---|---|
| (none) | Read-only (default) | 7 | General agents — page reads, queries, search, identity check |
--allow-write | Runtime writes | 13 | Agents that mutate existing content (pages, blocks, data-source contents) |
--allow-admin | Admin lifecycle | 18 | Operator-facing — schema mutation, relation wiring, page relocation, db update |
--allow-admin is tool-exposure policy, not a security sandbox. An agent running in an environment with an admin-scoped Notion integration token plus arbitrary code execution can hit the REST API directly regardless of MCP gating. What the flag actually provides:
- Prompt-injection attenuation — admin tools are absent from the agent's planning surface when the server is run in a lower tier, so a hijacked agent cannot choose an admin action.
- Accidental-action prevention — default Hermes/Claude profiles expose no admin tools, so an operator can't fat-finger a schema drop through an agent intended to be read/write only.
Agent runtimes should default to read-only and tier up only when a specific workflow requires it.
Setup
- Install the
notion-clibinary from crates.io:
Other install channels (prebuilt binaries, Homebrew formula) are documented in the project README with SHA-256 checksums published per release.cargo install notion-cli-mcp - Create an integration at https://www.notion.so/my-integrations and copy the Internal Integration Token. Use the least-privilege scopes the workflow actually needs.
- Export it:
export NOTION_TOKEN='ntn_...' - In Notion UI: open target page/database →
⋯menu →Connections→ add your integration.
Agent tools (MCP)
This section covers tools that are exposed over the MCP stdio interface to agent runtimes (Hermes, Claude). Admin-lifecycle operations are documented separately in Operator CLI — they're not exposed to agents by default.
Tier 1 — Read-only (6 tools)
Default when notion-cli mcp is invoked without flags.
# Search across the workspace
notion-cli search 'meeting notes' --filter '{"property":"object","value":"page"}'
# Retrieve one page
notion-cli page get <page-id-or-url>
# Inspect a database container (shows data_sources array)
notion-cli db get <database-id>
# Inspect a data source (shows schema — property names + types)
notion-cli ds get <data-source-id>
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-0xarkstar-notion-cli-mcp": {
"enabled": true,
"auto_update": true
}
}
}