Notion

Use it — Notion

How a Notion CLI command is built, output for scripts, and connecting an agent with a skill or MCP.

This page explains how a command is built, and how an agent uses the tool. Read it before your first command.

The profile comes first

A profile is a name you choose for one account. It is the first word of every command that uses an account:

notion personal config show

WCNOTION_PROFILE=personal does the same for one shell session. No profile is ever assumed, not even the only one: a command without one stops with exit code 2 and lists the profiles on this computer.

Output for scripts

Every command except mcp serve on stdin and stdout takes --json, and prints one JSON value on stdout. Errors are JSON on stderr, with a code to branch on. The command reference lists the codes.

Agents

notion skill install puts the tool's skill where Claude Code, Codex, Gemini CLI and OpenClaw look for it. notion skill install --for hermes also adds that folder to Hermes Agent's own settings, so a bare skill install leaves Hermes out. notion personal mcp serve serves the profile's commands over MCP, on stdin and stdout:

claude mcp add notion -- notion personal mcp serve

The server offers every command, the ones that write included. The profile's permissions decide what runs; see settings.

For ChatGPT and Claude in the browser, notion personal mcp serve --http --public-url https://laptop.example.ts.net serves on 127.0.0.1 (port 8765, or --port) behind your own tunnel. A browser app logs in with a one-time code that the command prints; notion personal mcp revoke ends every login. notion personal mcp server start runs the same server in the background, mcp server status shows its port, the login code and the apps logged in, and mcp server stop ends it.