notion — Claude Code skill

Operate Notion from Claude Code via the official REST API — search, query databases, read properties, create/update pages. Built because the built-in claude.ai Notion connector is slow and drops results. Pure Python standard library, zero dependencies: clone, paste a token, done.

Install

Clone into a Claude Code skills/ directory; the folder must be named notion:

Location	Path	Scope
User (recommended)	~/.claude/skills/notion	global — every project
Project	<project>/.claude/skills/notion	that project only

git clone <this-repo> ~/.claude/skills/notion

Set the token (once)

1. Create an Internal integration at https://www.notion.so/my-integrations and copy the secret (ntn_...).
2. Run setup and paste the token at the prompt:

   python3 ~/.claude/skills/notion/notion.py setup

   Input is hidden, whitespace/garbage is stripped, it's written to ~/.claude/.env, and the connection is verified.
3. Share each page/database with the integration in Notion: ... -> Connections -> your integration. Without this the API can't see it.

The token is read only from env / .env and never printed. .env is gitignored. In Claude Code, the skill guides you through setup on first use.

CLI

python3 notion.py search "keyword"           # pages + databases
python3 notion.py search "keyword" database  # databases only
python3 notion.py query <db_id>              # dump every row's properties

Library

from notion import Notion, prop, read_props

n = Notion()
db = n.find_database("Projects")             # keyword -> single database

rows = n.query_database(db["id"],            # filter/sort, auto-paginated
    filter={"property": "Status", "status": {"equals": "Todo"}},
    sorts=[{"property": "Due", "direction": "ascending"}])
for r in rows:
    print(read_props(r))                     # properties -> clean dict

n.create_page(db["id"], {"Name": prop.title("New task"),
                         "Status": prop.status("Todo")})
n.update_page(page_id, {"Status": prop.status("Done")})

Group	Functions
Search	search(query, type=None), find_database(keyword)
Query	query_database(db_id, filter=None, sorts=None) (auto-paginated)
Read	get_page(id), get_database(id), read_props(page), read_prop(p)
Write	create_page(db_id, props), update_page(page_id, props)
Build props	prop.title / rich_text / status / select / multi_select / number / checkbox / date / relation / people / url

Example

examples/tasks.py lists tasks in a database by status:

python3 examples/tasks.py <keyword|db_id> [status ...]

Need a full Python SDK? Use notion-client. This skill stays small and zero-dependency for use inside Claude Code.

License

MIT