notion-plus-mcp-server

A local MCP server for Notion built for precise edits. It changes exactly the block or field you point at, checks every value against the database schema before writing, previews risky changes, and records undo for the writes it supports (best effort; see Undo coverage).

Why this instead of the built-in Notion connector

Related MCP server: Notion MCP Server

Setup

1. Create a Notion integration. Go to https://www.notion.so/profile/integrations, create an internal integration, enable read content, update content, insert content, and (if you want automations to comment) insert comments, then copy the secret. To set people properties by name or email, also enable "Read user information including email addresses". Personal access tokens can't look up users at all; with one, pass user ids.

2. Share pages with it. In Notion, open each top-level page or database you want Claude to reach, click ••• → Connections, and add the integration. Everything under a shared page is included.

3. Install. Two ways:

• One-click bundle (Claude Desktop and Cowork). Download the .mcpb file for your computer (darwin-arm64 for Apple silicon Macs, darwin-x64 for Intel Macs, win32-x64, linux-x64) from the Releases page, double-click it (or drag it onto Claude Desktop's Settings → Extensions), and paste your integration secret when asked. You can also pick a folder uploads may come from and your time zone. Cowork runs inside Claude Desktop and uses the extensions installed there. Skip to step 5.

• From source (for Claude Code, or to run automations). Requires Node 22 or later.

git clone https://github.com/katekruger/notion-mcp.git
cd notion-mcp
npm ci
npm run build

To update later: git pull && npm ci && npm run build, then restart Claude (or start a new Claude Code session).

To build a bundle yourself: npm run bundle writes bundles/notion-plus-<version>-<platform>-<arch>.mcpb. Bundles are per platform because chart images use a native renderer; pushing a v* tag builds all four in GitHub Actions and attaches them to a release.

4. Connect it to Claude (from source). Use the full path to your clone.

Claude Code:

claude mcp add notion-plus --env NOTION_TOKEN=ntn_your_secret_here -- node /ABSOLUTE/PATH/TO/notion-mcp/dist/index.js
claude mcp list   # notion-plus should show as connected

Claude Desktop: open Settings → Developer → Edit Config, and add this to claude_desktop_config.json, then restart Claude Desktop:

{
  "mcpServers": {
    "notion-plus": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/notion-mcp/dist/index.js"],
      "env": { "NOTION_TOKEN": "ntn_your_secret_here" }
    }
  }
}

Turn off the built-in Notion connector while using this one so Claude doesn't pick between two sets of Notion tools. Keep the token out of the repo: it belongs only in your Claude config (or a local .env, which is gitignored).

5. Check it works. Ask Claude to "run notion_doctor". It checks the settings, the token, the integration's capabilities, whether any pages are shared with it, the local state folder, upload folders, and the chart renderer, and says how to fix anything that fails. Then ask "search Notion for "; you should see notion_search results with ids. If a setting is invalid (a misspelled time zone, say), the server still starts and every tool answers with the exact setting to fix. To call tools by hand instead, run NOTION_TOKEN=ntn_... npm run inspect to open the MCP Inspector.

6. Optional: scheduled automations. See Automations and GitHub Actions below.

Tools

Every tool answers with the same JSON shape:

{
  "status": "ok | partial | error",
  "summary": "one line",
  "data": { "...the tool's own result..." },
  "warnings": ["things to know, such as what couldn't be copied"],
  "undo": { "id": "a1b2c3d4", "coverage": "full | partial | none" },
  "pagination": { "next_cursor": "…" },
  "next_actions": ["what to do next, when there's something to do"]
}

Only status, summary, and data are always there. Results that would be too large shrink their longest lists and say how many items were left out (truncated); they're always valid JSON. Results that carry page, block, comment, or row text include a warning that the text is untrusted data, and the server's instructions tell the model the same: content in Notion pages isn't a source of instructions.

Read

• notion_search: find pages and databases by title.

• notion_get_page: properties plus a content outline with every block id, or (format: "markdown") the whole page as Notion-flavored markdown that can be written back.

• notion_get_blocks: read one section of a large page.

• notion_find_blocks: locate blocks by text or regex.

• notion_get_schema: property types, options, status groups, relations.

• notion_query: rows via where (equality, operators, in, or/and, relative dates) or raw Notion filters.

• notion_aggregate: counts, sums, averages, and more, grouped by any property or date bucket, without pulling rows into context.

Write content

• notion_patch_block: edit one block's text, checkbox, code language or caption, color, toggle heading, callout icon, or a table row's cells.

• notion_insert_blocks: add markdown or structured blocks at the start, end, or after a specific block.

• notion_replace_text: find and replace across a page's text, table cells, captions, and title, keeping formatting (dry run by default).

• notion_delete_blocks: trash specific blocks.

• notion_copy_blocks: copy blocks with everything inside them to another spot, or move them (move: true, dry run by default).

• notion_comments: list, add, and reply to comments.

Pages

• notion_update_page: title, icon, cover, lock, or move a page under another page or into a database.

• notion_duplicate_page: copy a page with its content, icon, cover, properties, sub-pages, and databases (schema and rows, or schema only with databases: "schema"). Sub-pages and databases keep their place in the page.

• notion_list_templates: a database's templates, for notion_create_page's template.

Write data

• notion_update_properties: set row fields with validation.

• notion_create_page: new row or sub-page with content, an icon and cover, or from a database template.

• notion_bulk_update: set values on every matching row, or different values per row (dry run by default, up to 500 rows).

• notion_bulk_create: add up to 1000 rows from JSON or CSV (dry run by default; every row validated first).

• notion_trash_page: trash a page.

Databases

• notion_create_database: a database with its full schema in one call: options (status options with groups), number formats, formulas, one- or two-way relations (including to itself), rollups, unique IDs, files, places.

• notion_schema: add, rename, or delete a property (delete previews first and undo restores the values), add select/multi-select/status options, change number formats and descriptions.

Views and visuals

• notion_views: list, read, create, update, and delete views: table, board, list, calendar, timeline, gallery, form, map, dashboard, and Notion's native chart views (column, bar, line, donut, number, with stacking). A view can be a database tab, a linked view placed anywhere on a page, or a dashboard widget.

• notion_create_chart: render a chart image (bar, column, stacked, grouped, line, area, pie, donut, scatter) from inline data or a database query, and refresh it in place later.

• notion_build_report: a report page for a database: summary, KPI numbers, live and image charts, a table of key rows (such as overdue items), and a Mermaid Gantt chart.

• notion_workflow: multi-step workflows with schedule, manual, or webhook triggers (see Workflows).

• notion_template: build pages from reusable templates (see Templates): list, get, validate, preview (outline, counts, and a diff against an existing page), render, save, delete, export, import.

Safety

• notion_history: changes and their undo ids, newest first, paged with cursor. Each says whether it's undoable, partly undoable, undone, or was interrupted part-way (with the tool's input, to check by hand).

• notion_doctor: check the setup and say how to fix what isn't working. Changes nothing.

• notion_capabilities: what the server can do with this integration (probed with read-only calls), the API version, and the limits that matter for planning.

• notion_undo: revert a change. Refuses if anything it would restore was edited afterward, and lists what; pass force: true to overwrite.

Automations (see below)

• notion_automation: list, add, update, validate, dry-run, enable, disable, delete, and run rules, and see recent runs.

API version

The server pins Notion API version 2026-03-11 (set NOTION_VERSION to override). That version renamed archived to in_trash, transcription blocks to meeting_notes, and replaced the flat after parameter of block appends with position; this server already used the new forms, and the full live suite passes on it.

Content formats

notion_insert_blocks and notion_create_page take markdown or structured blocks, and both can express every block type the API can create:

Inline: **bold**, *italic*, `code`, ~~strike~~, <u>underline</u>, [link](url), $x^2$, <span color="red">…</span> (any color, or blue_bg for backgrounds), and mentions: <mention-page url="…"/>, <mention-user email="…"/>, <mention-date start="2026-10-01"/>. A block's color goes at the end of its line: Text {color="blue"}.

These are the same tags Notion's markdown export uses, so notion_get_page with format: "markdown" returns markdown you can edit and insert back; the live test suite checks that a full page survives the round trip line for line. Local files can be uploaded from the working directory and the temp folder; set NOTION_PLUS_UPLOAD_DIRS (separated by :, or ; on Windows) to allow other folders.

The undo journal is stored in ~/.notion-plus/workspaces/<integration id>/journal.json (last 500 changes; see Local state). Each write is journaled before it reaches Notion: if the server stops mid-write, notion_history shows the entry as interrupted with the tool's input, so you can check those objects by hand. Undo restores the snapshot taken at write time. Before writing, it checks every page, block, or database it would restore; if any was edited after the original change (by a person, or by a later change through this server, which it names), it writes nothing and lists them. The check is per object, so an edit to a different field of the same page also counts, and edits in the same minute as the original change can't be seen. Undoing added options deletes them, which also clears them from any rows that used them since. Schema changes are the exception to the edit check: a database's edit time moves with every schema change, so it can't tell whose change it was; schema undo only touches the property it names.

Visuals: which to use

1. Native Notion content for structure and diagrams: callouts, columns, tables, equations, and Mermaid diagrams (```mermaid code blocks: flowcharts, sequence, Gantt, pie, timeline). Mermaid is checked before writing so a typo doesn't leave an error box.

2. Chart views (notion_views with type: "chart") when the data lives in a Notion database: they stay live, filter with the database, and people can click through. They can sit on any page as a linked view.

3. Chart images (notion_create_chart) for chart types Notion lacks, data from outside Notion, or a fixed snapshot. Types: bar, column, stacked and grouped columns, line, area, stacked area, pie, donut, scatter, and:

   • histogram (one row per observation; bins), boxplot (x = group, y = observation), heatmap (x = column, series = row, y = value)

   • waterfall (rows in order, y = change; a row with series "total" shows the running total), funnel (stages in order), bullet (actual and target rows per category)

   • small_multiples (one panel per series), dual_axis (two series: columns on the left axis, a line on the right), treemap (x = item, y = size, series = group), sankey (x = from, series = to, y = amount; flows must only go forward), network (x and series are the two ends of a link, y its weight; nodes sit on a circle sized by how connected they are)

   annotations add labeled reference lines ({at: "Q2", label: "Launch"} or {value: 100, label: "Target"}). Images use a colorblind-checked palette by default, thin marks, direct value labels, and a legend whenever there's more than one series; past eight series the smallest fold into "Other". palette switches to cool, warm, mono, or your own hex colors. Notion shows an image the same way in light and dark mode, so pick the surface with theme: light (default), dark, or transparent. format: "svg" uploads a vector image instead of a PNG. data_table: true adds a "Chart data" toggle under the chart with a one-line description and the numbers, so the chart has a text alternative (the description is also returned as alt_text). For anything else, pass a whole Vega-Lite spec as vega_lite: data must be inline, and specs that load URLs, link out, or use image marks are refused; vega_lite_theme picks its surface the same way. The recipe of a regular chart is stored in charts.json in the local state folder, and refresh_block_id redraws it from current data in the same block.

4. Embeds (embed blocks) for interactive charts hosted elsewhere, when neither of the above fits.

notion_build_report combines these: it uses a live chart view where Notion supports the chart type and renders an image otherwise.

Queries and aggregation

where in notion_query, notion_aggregate, notion_bulk_update, and automation rules accepts:

{
  "Status": {"in": ["Done", "At Risk"]},
  "Due": {"before": "today"},
  "Estimate": {">": 500, "<=": 1000},
  "Tags": "Q4",
  "Owner": null,
  "or": [{"Priority": "High"}, {"Task": {"contains": "urgent"}}],
  "$last_edited": {"after": "-7d"}
}

Operators: =, !=, >, >=, <, <=, contains, not_contains, starts_with, ends_with, in, not_in, is_empty, before, after, on_or_before, on_or_after, and date ranges such as past_week or next_month. Dates accept today, tomorrow, yesterday, and offsets like +7d, -2w, +1m (in NOTION_PLUS_TIMEZONE, default the system zone). Property names and option values are matched forgivingly and checked against the schema.

notion_aggregate takes group_by (a property, or {"property": "Due", "by": "month"}) and metrics such as ["count", "sum:Estimate", "avg:Estimate"]. Rows with several values (multi-select, people, relations) count once in each of their groups, and relation groups show the related rows' titles. It scans up to 10,000 rows by default (max_rows, up to 50,000).

Relation values in writes can be page ids, links, or the related row's exact title.

Undo coverage

Undo is best effort: it covers the writes below, from a snapshot taken at write time, and refuses when something it would restore was edited afterward.

Results say coverage: "partial" when part of a write can't be reverted (the entry names what), and none when nothing can. Undo can't see edits in the same minute as the original change (Notion reports edit times to the minute), entries roll off after 500 changes, and comments by other integrations, re-created unique IDs, and Notion-hosted files that expired can't be restored. A write interrupted by a crash is journaled as interrupted before it starts, so it's visible but may have nothing to undo.

Templates

notion_template builds a page from a declarative template, so a recurring page (a weekly update, a brief, a launch plan) is one call with values rather than dozens of block calls. Five ship with the server: weekly-executive-report, content-brief, launch-plan, research-dossier, and database-report (the page notion_build_report makes, as a template you can copy and change); get shows any of them as a starting point for your own, and save keeps yours in templates.json in the home folder (a saved template with a built-in's name replaces it).

A template declares its variables (type, required, default), then lists blocks:

{
  "version": 1,
  "name": "weekly-update",
  "variables": { "week_of": { "type": "date", "required": true }, "wins": { "type": "list", "default": [] } },
  "title": "Week of {{week_of}}",
  "blocks": [
    { "kpis": [{ "label": "Open tasks", "metric": { "database": "https://www.notion.so/…", "value": "count", "where": { "Status": { "not": "Done" } } } }] },
    { "if": "wins", "then": [{ "heading": "Wins" }, { "each": "wins", "as": "w", "blocks": [{ "markdown": "- {{w}}" }] }] },
    { "chart": { "spec": { "type": "line", "title": "Signups" }, "source": { "database": "https://www.notion.so/…", "x": { "property": "Created", "by": "week" }, "y": "count" } } },
    { "slot": "notes" }
  ]
}

Blocks can be markdown, headings, callouts, toggles, columns, dividers, KPI numbers (fixed, or computed from a database), charts (any notion_create_chart type, from data or a database query), live database views (top level), tables (fixed rows or a database query), a database summary callout (summary: rows, completion, overdue), Mermaid Gantt charts (fixed tasks, or query for a database's dated rows), and raw block specs. Where a field takes an object or list (a where, a table's properties), it can also be a whole "{{variable}}" that holds one. each repeats blocks for every item of a list ({{item.field}}, {{item_index}}), if picks blocks by a condition ("var" for set and non-empty, or {var, equals | not | in | gt | lt | empty}), parts are named block lists a template reuses with {part, with}, and slots are filled at render time with markdown or blocks. Every variable is checked before anything is written, and a reference to a value that doesn't exist is an error rather than a blank in the page. preview shows the outline, the charts and views it would make, an estimate of the Notion requests, and, with compare_to, a line diff against an existing page; render creates the page under parent or appends to append_to, and notion_undo removes what it wrote.

Known Notion API limits

• A block's type can't be changed in place; insert a new block and delete the old one.

• Blocks can't be moved, so notion_copy_blocks with move: true copies and then trashes the original: moved blocks get new ids and lose their comments. It refuses moves that would lose content the API can't recreate (databases, read-only blocks) or break synced-block references. Pages are moved natively.

• There's no API for duplicating a page or a database; notion_duplicate_page rebuilds both. Databases directly on the page are recreated in place with their schema and up to 500 rows per data source (values and content); relations inside the copied database point at the copied rows, while a two-way relation to a database outside the copy becomes one-way so nothing outside the copy changes. Views aren't copied (the copy gets a default table view), and linked database views can't be read through the API, so both are reported. Notion only creates pages and databases directly on a page, so sub-pages inside toggles or columns go to the end of the copy and databases there are skipped.

• Button blocks can't be created or read through the API. Breadcrumbs, bookmarks, and links to pages don't appear in Notion's markdown export; this server fills them in. Code captions aren't in the markdown export either.

• A heading 4 can't be updated without resending its text; notion_patch_block handles that.

• Notion's built-in database automations can't be created or edited through the API. Button blocks, AI blocks, and some embeds are read-only (the API returns them as unsupported).

• Map views need a place property (map_by). Dashboards can be created and given widgets, but the widget layout beyond "new row" or "existing row" is set in Notion.

• A chart image can be replaced in place, but Notion won't take an old file link back, so a refresh keeps a copy of the previous image in ~/.notion-plus/charts/ for undo.

• Status options can be added, each in a group (To-do, In progress, Complete). Options sent without a group all land in To-do, so this server guesses the group from the option name ("Done" → Complete) and says so.

• Last-edited times are rounded to the minute, so the freshness check catches edits made in an earlier minute.

• Select and status option names and colors can't be changed through the API. Renames are accepted and silently ignored; color changes are rejected. Rename options in Notion, or add a new option, move rows with notion_bulk_update, and delete the old option in Notion.

• Leaving an option out of a schema update deletes it and clears it from every row, so this server always sends the full list.

• Verification properties can only be created in wikis; in a regular database Notion skips them without an error (notion_create_database reports it).

• There's no aggregation endpoint; notion_aggregate reads the matching rows and summarizes them on your machine (about 100 rows per request). Rows with more than 25 relations or people are counted by their first 25.

• Deleting a property deletes its values. notion_schema saves up to 2000 rows' values first so undo can put them back; a re-created unique ID renumbers rows, and a re-created two-way relation re-creates its other side.

• One write can carry at most 100 relations or people, and at most 100 rich text segments per block or property (each segment up to 2000 characters). This server splits long text into segments and returns a clear error past those limits instead of truncating.

• blocks.children.append accepts 2 levels of nesting per request; deeper content is added in follow-up requests automatically.

• Page reads include at most 25 items of a title, rich text, relation, or people value. Undo snapshots and before/after previews re-read the full value, so nothing is lost; notion_get_page and bulk dry-run previews may still show only the first 25.

• New databases take a few seconds to appear in notion_search.

• Notion merges adjacent text segments with identical formatting when you read them back, and normalizes link URLs (for example adding a trailing /).

• Undoing a large insert trashes blocks one request at a time (about 3 per second).

• A comment can only be deleted by the integration that created it, so undo can remove comments this server added, but nothing else.

• Requests time out after 30 seconds (NOTION_TIMEOUT_MS). Reads are retried after timeouts and dropped connections; writes are not, since the first attempt may have landed. Notion's 429 and 5xx responses are retried by the client, honoring Retry-After.

• Results are capped at 25,000 characters. Long lists are shortened (with a count of what was left out) so the result stays valid JSON; narrow the request to see the rest.

Automations

Rules run on a schedule in GitHub Actions (or locally with npm run automations). Rules you manage from Claude are saved in rules.json in the local state folder, so they survive reinstalling or upgrading the server; the GitHub workflow runs the committed automations/rules.json (it sets NOTION_PLUS_RULES to it). Upgrading from 0.9 or earlier, rules already in automations/rules.json of your checkout are copied to the new location the first time. A rule picks rows with a condition, runs at set times, or both, and acts on what it finds. Manage rules from Claude with notion_automation ("add an automation that…"), which checks each rule against the live database and previews it before saving.

{
  "version": 1,
  "timezone": "America/New_York",
  "rules": [
    {
      "id": "at-risk",
      "schedule": "weekdays 09:00",
      "database": "https://www.notion.so/…",
      "when": { "where": { "Due": { "before": "today" }, "Status": { "not_in": ["Done", "At Risk"] } } },
      "actions": [{ "set": { "Status": "At Risk" } }, { "comment": "Past due: {{page.Task}} was due {{page.Due}}" }]
    },
    {
      "id": "stamp-completed",
      "database": "https://www.notion.so/…",
      "when": { "where": { "Status": "Done", "Completed Date": null } },
      "actions": [{ "set": { "Completed Date": "{{today}}" } }],
      "then": [{ "refresh_chart": "<chart image block id>" }]
    },
    {
      "id": "weekly-report",
      "schedule": "weekly mon 08:00",
      "then": [{ "build_report": { "database": "https://www.notion.so/…", "parent": "https://www.notion.so/…", "title": "Week of {{today}}" } }]
    }
  ]
}

When a rule runs. With only when, every run (hourly in GitHub Actions) checks for matching rows. With a schedule ("hourly", "daily 09:00", "weekdays 09:00", "weekly mon 09:00", "monthly 1 09:00", or 5-field cron, in the file's timezone), the rule fires once per scheduled time, on the first run at or after it; with both, the condition is checked only at those times. Because the workflow runs at minute 17, "weekdays 09:00" fires at about 9:17.

Conditions (when): where and filter work exactly like notion_query, including operators and relative dates. relative takes {property, older_than_days | newer_than_days} for a date, created time, or last edited time property, or "$created" / "$last_edited".

Row actions (actions), applied to each matching row: {"set": {...}} (validated like notion_update_properties), {"append": "markdown"} or blocks, {"comment": "text"}, {"trash": true}.

Follow-up actions (then), run once per firing after the row actions (and, when the rule has a condition, only if it acted on at least one row):

• {"refresh_chart": "<block id>"}: redraw a chart made by notion_create_chart or a report. When you save the rule through notion_automation, the chart's recipe is copied into the rule so the GitHub runner can redraw it.

• {"build_report": {...}}: the same arguments as notion_build_report. replace_previous (on by default) trashes the report this rule built last time.

• {"create_page": {"parent", "title", "template"?, "properties"?, "markdown"?}}.

Strings can use {{today}} (in the file's timezone), {{now}}, and in row actions {{page.<Property>}}, {{page.url}}, {{page.id}}.

Each rule acts once per row. A rule must stop matching a row after acting on it, or it would act again on every run. The runner refuses a rule unless it writes a value its condition no longer matches (for example Status: {"not_in": ["Done", "At Risk"]} then setting "At Risk"), trashes the row, or names a marker: a checkbox property the runner requires to be unchecked and then checks. Scheduled rules also remember which scheduled time they last fired for, so a time fires once even if runs overlap or repeat.

Order, retries, and partial failure. Each row's actions run as steps, and progress is saved after every step: first set values that keep the row matching, then append and comment, then the writes that take the row out of the condition (the marker, or set values for properties the condition checks), then trash. A row is only marked handled once everything before it landed. If a step fails, the row keeps matching, and the next run picks it up again from the step that failed, skipping the ones that succeeded. A scheduled occurrence only counts as fired when every row and every then action of it succeeded; otherwise the next run retries it (completed then actions aren't repeated), until it succeeds, a newer occurrence arrives, or you waive it. An edited rule starts unfinished rows over. Each rule's run reports succeeded, partial (some steps failed or were left for the next run), failed, or skipped (not due).

Other options: enabled (default true), limit (rows per run, default 50; the rest wait for the next run), allow_new_options, data_source_name, name.

Managing rules from Claude

notion_automation handles every step: list, get, add, update (merge fields), validate (check a rule and preview what it would do), dry_run (never writes; force: true ignores schedules), enable, disable, delete, run (writes; one undo id per rule; returned as an error unless every rule succeeded, with the details and undo ids kept), history (local runs, newest first, paged with limit and cursor), waive (give up on a rule's unfinished firing: the occurrence counts as fired and unfinished rows start over), export and import (the whole rules file as JSON; import_mode merge or replace), and deploy (the rules file with chart recipes embedded, plus the steps to run it in GitHub Actions). list and get return the file's revision; passing it back as expected_revision refuses the edit if the file changed in the meantime.

Running locally

npm run automations -- --dry-run            # preview every enabled rule that's due
npm run automations -- --dry-run --force    # preview as if every schedule were due
npm run automations -- --rule at-risk --force
npm run automations                         # apply

One run stops starting new rows once it reaches any of its limits: 200 rows (--max-rows, AUTOMATIONS_MAX_ROWS; the old --max-writes still works), 3000 Notion requests (--max-requests), 5000 appended blocks (--max-blocks), or 20 minutes (--max-minutes). Rows left over run next time, and the run reports partial. A failing rule is reported and the others still run. The command exits non-zero unless every rule succeeded, and logs one JSON line per event on stderr, each with the run's run_id (NOTION_PLUS_LOG=text for plain lines, off to silence). Each rule's run is one journal entry, so notion_undo <undo_id> reverts it, including deleting the comments it added and trashing pages it created. Runs are logged to automation-runs.jsonl, and schedule state is kept in automation-state.json, both in the local state folder.

GitHub Actions

.github/workflows/automations.yml runs every hour (at minute 17) from the committed automations/rules.json. It never lets two runs overlap. Schedule state (which occurrences fired, and unfinished rows and occurrences to resume) is committed after every run to the notion-automations-state branch, which only holds automation-state.json (no page content). Once that branch exists, a run whose state can't be restored stops instead of re-firing old occurrences. The undo journal and run log carry over in the Actions cache (best effort: an evicted cache only shortens undo history) and are uploaded as an artifact (notion-plus-journal-<run id>, kept 90 days). When a run fails or is partial, it opens an issue labeled notion-automations (creating the label if needed) or comments on the open one; if that isn't possible, the job summary says so. The manual Run workflow button takes dry_run (on by default), rule, and force.

One-time setup

1. Make a token for the job. Create a separate internal integration (step 1 of Setup) and share only the pages and databases your rules touch with it (including report parents). Enable insert comments if rules comment. This limits what the scheduled job can reach.

2. Add it as a repository secret. Open the repo on GitHub, click the repo's Settings tab, then Secrets and variables → Actions → New repository secret. Name it NOTION_TOKEN and paste the token.

3. Test the workflow. Go to Actions → Notion automations → Run workflow, leave "dry run" checked, and run it. A green run whose summary lists your rules (or "No enabled rules.") means the token and workflow work.

Adding a rule

1. In Claude, ask for it in plain words, for example: "Every weekday at 9am, mark rows past their due date as At Risk and add a comment." Claude uses notion_automation, which checks the rule against the live database, shows the rows it would act on, and saves it on your machine.

2. Ask Claude to deploy the rules (notion_automation deploy), save the returned file as automations/rules.json in your repository, and commit and push it. (If you work in a checkout with NOTION_PLUS_RULES pointing at automations/rules.json, edits land there directly.)

3. Run the workflow once by hand with "dry run" checked (and "force" to see a scheduled rule now), and read the summary. After that, the hourly runs apply it.

To pause a rule, disable it (or set "enabled": false) and push. To give up on an occurrence that keeps failing, waive it (locally, on a state file restored from the notion-automations-state branch) or fix the cause; it's retried every run until then. To stop everything, disable the workflow under Actions → Notion automations → ••• → Disable workflow.

Undoing a scheduled run

Download the run's notion-plus-journal-<run id> artifact, unzip it into a folder (it keeps the workspaces/<integration id>/ layout), point NOTION_PLUS_HOME at that folder (in your Claude config, or NOTION_TOKEN=… NOTION_PLUS_HOME=… npm run inspect), and call notion_undo with the undo id from the run summary.

GitHub may start scheduled runs a few minutes late, and turns off schedules in repos with no activity for 60 days.

What Notion itself can't do through the API

• Notion's built-in database automations (the ⚡ button in a database) can't be created, read, or changed through the API. Rules here are the programmable alternative; they poll rather than react instantly.

• Webhooks can push changes the moment they happen, but Notion needs a public HTTPS URL to deliver them, and a local server doesn't have one. A future option: a small hosted endpoint (or a tunnel such as Cloudflare Tunnel) that receives the webhook and triggers the workflow with workflow_dispatch, so rules run within seconds instead of within the hour.

Modes

Workflows

Workflows are version 2 of automations: a trigger and a list of steps that run in order, with outputs that later steps use. Manage them with notion_workflow (save, run, runs, run_status, resume, cancel, convert, …); they're kept in workflows.json in the home folder (NOTION_PLUS_WORKFLOWS moves it; the GitHub workflow uses the repo's automations/workflows.json). Rules keep working, and convert turns a rule into an equivalent workflow (saved disabled, so you can check it first).

{
  "version": 2,
  "id": "launch-review",
  "trigger": { "webhook": { "events": ["page.properties_updated"], "database": "https://www.notion.so/…" } },
  "steps": [
    { "id": "ready", "query": { "database": "https://www.notion.so/…", "where": { "Status": "Ready for review" } } },
    { "id": "each", "foreach": { "items": "${steps.ready.rows}", "as": "row", "steps": [
      { "id": "ask", "approval": { "page": "${row}", "property": "Approved", "message": "Approve ${row.title} for launch?" } },
      { "id": "ship", "set": { "page": "${row}", "values": { "Status": "Launched", "Launched on": "${today}" } } },
      { "id": "tell", "slack": { "webhook": "${secret:launch_slack}", "text": "Launched: ${row.title} ${row.url}" }, "retry": { "attempts": 3 } }
    ] } }
  ],
  "on_failure": [{ "comment": "https://www.notion.so/…ops-page" }]
}

Triggers: manual (always available through run), schedule (same forms as rules, in the server's time zone), and webhook (Notion events, optionally only for one database).

Steps: each has an id, and may have if (a ${…} reference that must be set and not empty), retry (attempts, backoff_seconds), timeout_seconds, and continue_on_error. Actions:

• Notion: query (rows with id, url, title, and every property), set, append, comment, create_page, move_page, duplicate_page, trash, replace_text, export_markdown, render_template.

• Outside: http (to hosts listed in NOTION_PLUS_HTTP_ALLOW, comma-separated, *.example.com allowed) and slack (an incoming-webhook URL, best kept as a secret).

• Control: foreach (over a list, ${item} or the as name), switch (cases by value), approval (pauses until a checkbox is checked or a comment containing a keyword is posted; optional request comment and expiry), delay (pauses for minutes), and run_workflow (another workflow, with inputs).

References: ${steps.<id>.<path>}, ${trigger.*} (for webhooks: event, page_id, entity, data), ${inputs.*}, ${today}, ${now}, and ${secret:NAME}, read from the environment variable NOTION_PLUS_SECRET_NAME. Secret values are replaced with *** everywhere a run is stored or shown.

Durable runs. Every step's state is saved as it changes. A run that fails, pauses, or is interrupted continues after the last finished step (resume, or the next scheduler pass). A step that started but didn't finish is retried as a resume: creating steps first look for what the interrupted attempt already made (a page with the same title, a comment with the same text, appended blocks created since it started) and adopt or remove it, so retries don't duplicate content; HTTP steps send an Idempotency-Key header for the same reason. (Rules get the same protection for retried appends.) Each run records undo for what it wrote, and on_failure reports failed runs to Slack, an HTTP endpoint, or a page comment. Set NOTION_PLUS_NOTIFY (for example slack:ops_slack,comment:<page>) to be told about failed or partial rule runs too.

Scheduling. Each npm run automations (hourly in GitHub Actions) also starts scheduled workflows that are due and continues waiting runs whose approval or delay has come. Run state is saved on the notion-automations-state branch with the rules' state.

Webhook mode

npm run webhook (or the Dockerfile) runs a small server that reacts to Notion events within seconds instead of within the hour:

1. Run it somewhere Notion can reach over HTTPS (behind a reverse proxy, a tunnel such as Cloudflare Tunnel, or a platform that terminates TLS), with NOTION_TOKEN, a persistent NOTION_PLUS_HOME (the container uses /data), and optionally NOTION_PLUS_WEBHOOK_PORT (default 8787).

2. In the integration's settings, add a webhook subscription to https://<your host>/notion/webhook. Notion sends a verification token; the server logs it. Paste it into Notion to verify, and set NOTION_PLUS_WEBHOOK_TOKEN to it (restart).

3. Give workflows a webhook trigger.

Every delivery must carry a valid X-Notion-Signature (HMAC-SHA256 of the body with that token). Events are accepted once (by id, remembered for a week), only if they're less than 10 minutes old, and acknowledged right away; a worker then starts the matching workflows, retrying with backoff, and moves an event that fails five times to dead letters. notion_workflow events lists the queue, replay retries an event, and discard drops one. GET /healthz reports queued and dead events. The same worker continues waiting runs and starts scheduled workflows every minute, so hourly polling becomes a fallback.

Local state

Everything the server remembers lives under ~/.notion-plus (NOTION_PLUS_HOME moves it), in a folder per integration: workspaces/<integration id>/, with journal.json (undo history), charts.json (chart recipes), automation-state.json (which scheduled occurrences fired), and automation-runs.jsonl (run log). Two integrations sharing a machine never mix their history. NOTION_PLUS_WORKSPACE sets the folder name instead of looking up the integration; NOTION_PLUS_STATE moves just the automation state file. The first time a folder is created, state from older versions (kept directly in ~/.notion-plus) is copied into it.

These files are safe to share between several servers at once (Claude Desktop, Cowork, Claude Code, the scheduled runner): each change is made under a lock, written to a temporary file, flushed, and swapped in, with the previous version kept as <file>.bak. If a file can't be read (cut off by a crash or a full disk, edited by hand into invalid JSON, or not readable), the server stops with an error naming it instead of treating it as empty, since that would lose undo history or repeat scheduled automations. Fix the file, restore the .bak, or move it away to start fresh. A leftover <file>.lock from a process that died is cleared automatically.

Development

npm test                 # offline unit and property tests with vitest (no network)
npm run test:coverage    # the same, failing if coverage drops below the thresholds in vitest.config.ts
npm run lint             # ESLint (typescript-eslint strict)
npm run typecheck        # src, scripts, and tests
npm run check            # lint, typecheck, tests with coverage, build; CI runs this on Node 22 and 24
npm run check:version    # package.json, manifest.json, package-lock.json, and CHANGELOG.md agree
npm run test:live        # live integration suite against a real workspace
npm run bundle && node scripts/bundle-smoke.mjs   # build this platform's bundle and install-test it

CI also fails on known high-severity advisories in runtime dependencies, reviews new dependencies in pull requests (on public repos, or private ones with GitHub Code Security once the repository variable DEPENDENCY_REVIEW is true), and Dependabot proposes updates weekly. Every GitHub Action is pinned to a commit. A release builds a bundle on each platform, install-tests it (unpack, start, list every tool, render a chart), and publishes it with sha256sums.txt, an SBOM, and build provenance.

Live tests in CI. .github/workflows/live.yml runs the smoke and acceptance suites nightly and on release tags once two repository secrets exist: NOTION_TOKEN (an integration used only for testing, in a throwaway workspace) and NOTION_TEST_PAGE (a page shared with it). Until then it passes with a notice. It never runs for pull requests, so forks can't reach the secrets.

Evaluations and acceptance tests

• evals/notion-plus.xml holds 10 realistic, read-only questions (in the MCP evaluation format) that each need several tools to answer: aggregation, relations, schema, views, page content, and comments. npm run eval:seed builds the fixed dataset they're written against under your test page; npm run eval:verify answers every question through the tools and checks the expected answers. To measure how well a model picks tools, run the questions with the MCP evaluation harness against this server.

• npm run acceptance runs the seven acceptance scenarios (project tracker, views, report page, find/replace with preview and undo, the At Risk and Completed Date automations, and a 300-row bulk update with undo) and leaves the results under an "Acceptance " page.

npm run test:live (also npm run smoke) needs NOTION_TOKEN and NOTION_TEST_PAGE (a page shared with the integration), from the environment or a local .env file (gitignored). It creates two throwaway databases under that page, runs every tool including dry runs and notion_undo for each write type, then moves them to the trash. It never writes outside the test page, and its undo journal goes to a temp folder. Set SMOKE_KEEP=1 to keep the databases for inspection.

Versions follow semver; see CHANGELOG.md and, for supported versions and deprecations, SUPPORT.md.

Roadmap

Built in phases, each ending with the build, unit tests, and the live suite passing:

1. Foundations: tests, lint, CI, timeouts, partial-failure reporting, safer undo. (done, 0.2.0)

2. Content: every creatable block type, rich text colors and mentions, markdown round trip, move/copy/duplicate, icons, covers, templates, comments. (done, 0.3.0)

3. Databases: create with full schemas, schema editing (including status options), every property type, aggregation, bulk create. (done, 0.4.0)

4. Views and visuals: views including native chart views, generated chart images, Mermaid, report pages. (done, 0.5.0)

5. Automations: schedules, run state, more actions, full management from Claude. (done, 0.6.0)

6. Distribution: MCP Bundle, tool evaluations, acceptance tests, API version 2026-03-11. (done, 0.7.0)

Next: hosted team mode (multi-user, OAuth, a shared database); see docs/hosted-design.md.