notion

name	notion
description	Notion access from Claude Code via the official MCP connector (default path, ~95% of intents) or the `ntn` CLI (only for file uploads, Notion Workers, headless/CI scripts, raw API discovery, shell piping). Routes intent to the right transport, pre-flights the Notion-flavored Markdown spec and target data-source schema, and pins the empirical gotchas not surfaced by tool descriptions or `ntn --help`. Use whenever the user wants to read, fetch, search, create, update, query, or organize Notion content — pages, databases, data sources, views, comments, blocks, properties, schemas, wikis, docs — or upload a file to Notion, build a Notion Worker, or script Notion non-interactively. Triggers on Notion, Notion page, Notion database, Notion DB, Notion wiki, Notion doc, Notion comment, Notion view, Notion property, Notion schema, Notion file, Notion Worker, NOTION_API_TOKEN, ntn, ntn api.
when_to_use	When the user wants to read, write, query, search, or organize Notion content (pages, databases, data sources, views, comments, blocks, properties, schemas, wikis, files), build a Notion Worker, or script Notion non-interactively. Skip when the user is in the claude.ai web app (different surface, native handling), has explicitly disabled the Notion MCP connector AND has not installed the `ntn` CLI, when the input is a local Notion export (ZIP/HTML/MD) — use /markitdown — or when the request targets a different knowledge tool (Linear, Confluence, Coda, Obsidian).
license	MIT
compatibility	Optimized for Claude Code; degrades gracefully on any agent implementing the Agent Skills standard.
metadata	{"author":"coroboros","sources":["developers.notion.com/guides/mcp/overview","developers.notion.com/cli/reference/commands","developers.notion.com/page/changelog","developers.notion.com/reference"]}

Notion

Default path is the official Notion MCP connector — covers ~95% of intents (pages, databases, views, comments, search, blocks, users, teams). The ntn CLI is optional and used only for the five cases listed under Routing below. The skill routes the user's intent to the right transport, runs the Pre-flight before the first content write, and applies the Gotchas — empirical facts not surfaced by tool descriptions or --help.

Pre-flight (do once per session before any content write)

MCP path only — on the ntn CLI branch, skip this and validate shapes against the REST API responses instead.

1. Read the MCP resource notion://docs/enhanced-markdown-spec — the canonical reference for Notion-flavored Markdown used by notion-create-pages content and notion-update-page update_content / replace_content. Don't guess Markdown syntax — Notion's flavor diverges from CommonMark in non-obvious ways.
2. For database row CRUD — notion-fetch the target data source first. The fetch returns the current SQLite-style schema. Property names are case-sensitive; expanded keys apply (date:<col>:start | :end | :is_datetime, place:<col>:name | address | latitude | longitude | google_place_id, checkbox __YES__ / __NO__, properties literally named id or url → prefix userDefined:).

Routing — MCP vs CLI

Default — MCP

For ~95% of Notion intents. The MCP wraps the API in DSLs that have no CLI equivalent:

• SQL DDL for schemas — notion-create-database / notion-update-data-source
• View DSL — notion-create-view / notion-update-view
• Block-level comments — selection_with_ellipsis against rendered Markdown
• Batch up to 100 rows in one notion-create-pages call
• Semantic search across connected sources (Slack, GDrive, GitHub, Jira, MS Teams, Sharepoint, OneDrive, Linear)

Use the ntn CLI when (and only when):

• File upload to Notion — . The MCP has no upload tool.