What it does

Automates Notion through CLI scripts rather than always-on integrations. Four primitives cover most automation needs: search, create page, append blocks, and query database.

The pattern

Four primitives:

• Search. Find pages and databases by title. Returns page IDs for use in other operations. Filters by last-edited time to find recent content.
• Create page. Create a new page in a specific database or as a child of an existing page. Set properties (title, status, tags, dates) at creation time.
• Append blocks. Add content to an existing page: paragraphs, headings, bullet lists, code blocks, callouts, dividers. Append-only by design. Does not modify existing content.
• Query database. Filter and sort database entries. Supports compound filters (status = "Active" AND priority = "High"). Returns structured property data.

Three workflows built from the primitives:

1. Knowledge capture. When a decision is made or an insight surfaces during work, immediately create a page in the decisions database with the context, rationale, and date. Do not wait for a weekly review. Decisions captured in the moment include context that is lost by Friday.

2. Research documentation. Create structured briefs: problem statement, sources consulted, key findings, recommendations. Each source is a linked block with the URL and a summary. The brief is a page in a research database, queryable by topic and date.

3. Spec-to-implementation. Parse sections of a specification document and create one task per section in a project database. Each task links back to the source spec section. Progress on tasks maps directly to coverage of the spec.

Key decisions

CLI scripts over MCP server. An MCP server loads its entire schema into every AI agent's context window, whether or not the agent needs Notion access. That is thousands of tokens per session, wasted. A CLI script adds zero tokens until explicitly invoked. The agent calls the script like any other command, and the token cost is limited to the script's output.

Append-only content operations. Notion's block API supports updates and deletes, but append-only is safer for automation. You never accidentally overwrite someone's manual edits. If content needs to change, create a new version or add a correction block.

Page IDs are the coordination key. Every operation either takes or returns a page ID. Scripts compose by passing IDs between them: search returns an ID, append uses that ID, query returns IDs for batch operations.

Store scripts alongside your project, not globally. Notion automation scripts are project-specific (they target specific databases and page structures). Keep them in the project repo, not in a global tools directory.

When to use it

When you want AI agents or automation scripts to read from and write to Notion without manual copy-paste. When decisions, research, or tasks are tracked in Notion and you want them updated as part of automated workflows. When you need structured data in Notion to stay synchronized with work happening in code.