Version2.0.0
Categoryproductivity
AuthOAuth 2
Tools31
Transportstdio
LicenceMIT
01
What it does
The app, in its own words.
Notion workspace - pages, databases, blocks, search, comments, file uploads
02
Tools
31 tools the agent can call.
Every one is declared with typed parameters and returns structured results, so the host can render them instead of narrating them.
- append-blocksAppend blocks as children of a page or block. Supports paragraph/heading_1..heading_4 (H4 added in v5.16) and paragraph blocks accept an `icon` for inline emoji/external/file icons. `position` chooses placement: { type: 'after_block', after_block: { id } } | { type: 'start' } | { type: 'end' (default) }. Returns curated { blocks, appendedCount, parentId }. Not retryable (no idempotency key — creates duplicates on retry).
- create-advanced-blocksCreate an advanced block. Supported types: 'callout' (icon + colour), 'toggle' (children), 'synced_block', 'meeting_notes' (summary + transcript), 'paragraph' (with optional `icon` per v5.16). `content` must match the Notion shape for the given `blockType`. Not retryable.
- create-column-layoutCreate a column_list with N columns on a page. `columns` is an array of arrays of Notion block objects (one inner array per column). Not retryable.
- create-commentPost a comment on a page (pass pageId) or reply to a discussion (pass discussionId). Returns the curated comment { id, pageId, parentBlockId, authorId, plainText, createdTime }. Not retryable.
- create-databaseCreate a new database as a child of a page. Returns curated { id, url, title, schema, icon, cover, createdTime, parentType, parentId }. Not retryable (no idempotency key).
- create-database-itemInsert a new row (record) into a Notion database. Add to table, create table item, append database row. Pass `properties` as a flat agent-friendly map: `{ Title: "Spec", Status: "In review", Tags: ["urgent"], Assignee: ["<user-uuid>"], DueDate: "2026-05-06" }`. The handler resolves the schema and serialises each value into Notion's verbose shape automatically. Returns the curated created page. Multi-source DBs: pass `dataSourceId` to target a specific source.
- create-pageCreate a new page under a page (parentType='page') or database (parentType='database'). For database parents, the row is added to the first data source unless `dataSourceId` is provided. Returns curated { id, url, title, icon, cover, parentType, parentId, createdTime }. Not retryable (no idempotency key).
- delete-blockDelete (archive) a block. Returns the curated archived block { id, type, archived, lastEditedTime }. Idempotent — retries are safe.
- delete-commentDelete a comment by id. Returns { id, deleted: true }. Destructive: a deleted comment cannot be recovered. Idempotent — re-deleting an already-deleted comment is a no-op from the agent perspective (Notion 404s, we coerce to deleted=true).
- duplicate-pageDuplicate a page including icon/cover/properties/children blocks. Returns { sourcePage, duplicate } with curated shapes. Not retryable — creates new pages each call.
- get-blockRetrieve a block. Returns curated { id, type, plainText, hasChildren, checked, language, caption, url, createdTime, lastEditedTime }. Params: blockId, fields?, includeRaw.
- get-block-childrenDEPRECATED — prefer `get-page-content` (markdown) or `get-blocks` (paginated raw). Kept for back-compat: returns { textContent } as recursive markdown. Pass includeBlockIds=true to embed `<!-- block: id -->` comments before each top-level block.
- get-blocksList direct children of a page/block with pagination. Returns curated { id, type, plainText, hasChildren, ... }. Use when you need block IDs + structure. For rendered markdown use `get-block-children` or `get-page-content`. Params: blockId, limit (1-100, def 25), cursor, fields?, includeRaw.
- get-databaseRetrieve a database. Returns curated { id, url, title, description, icon, cover, schema, createdTime, lastEditedTime, parentType, parentId, archived }. Params: databaseId, fields?, includeRaw.
- get-meReturn the bot user (this integration). Returns curated { id, name, type, avatarUrl, email, bot }. Params: fields?, includeRaw.
- get-pageRetrieve a page. Returns curated { id, url, title, icon, cover, properties, createdTime, lastEditedTime, parentType, parentId, archived }. Params: pageId, fields?, includeRaw.
- get-page-markdownRetrieve a page's full content as markdown using the native Notion v5 endpoint. Replaces `get-page-content` (eliminated 2026-05). Pass `includeTranscript=true` to inline meeting_notes transcripts. Response: { markdown }.
- get-userRetrieve a user by ID. Returns curated { id, name, type, avatarUrl, email, bot }. Params: userId, fields?, includeRaw.
- list-commentsList comments on a page/block. Returns curated rows { id, pageId, parentBlockId, discussionId, authorId, plainText, createdTime }. Params: blockId, limit (1-100, def 50), startCursor, fields?, includeRaw.
- list-usersList workspace users. Returns curated rows { id, name, type, avatarUrl, email, bot }. Params: limit (1-100, def 50), startCursor, fields?, includeRaw.
- query-databaseQuery database rows with filter + sorts. Returns curated rows { id, url, title, icon, properties, lastEditedTime }. `properties` whitelist controls which columns travel (default: title only). Pass `dataSourceId` directly for multi-source DBs; otherwise the first data source is used. Filter accepts the standard Notion shape: { property, <type>: { <op>: <value> } } — single-value ops only (Notion v5 does NOT support equals_any). To match any of N values, compose with `or`: { or: [ { property: 'Status', status: { equals: 'Done' } }, { property: 'Status', status: { equals: 'In review' } } ] }. Params: databaseId | dataSourceId, filter?, sorts?, propertyNames?, limit (1-100, def 50), startCursor, fields?, includeRaw.
- searchSearch pages & databases by title. Returns curated rows { id, object, url, title, icon, lastEditedTime }. Params: query, filter?, sort?, limit (1-100, def 50), startCursor, fields?, includeRaw.
- set-page-coverSet a page's cover image from an external URL. Returns curated { id, url, title, cover, lastEditedTime }. Idempotent.
- set-page-iconSet a page's icon (emoji or external URL). Returns curated { id, url, title, icon, lastEditedTime }. Idempotent.
- update-blockReplace `oldText` with `newText` in a block's text. Reads the block, verifies `oldText` exists (exact match), then updates preserving annotations. Errors with 'Text not found in block. No changes made.' when oldText doesn't match. Returns the curated block { id, type, plainText, lastEditedTime }.
- update-commentEdit an existing comment. Pass plain `text` for a simple string body, or `richText` for full Notion rich-text formatting. Returns the curated updated comment { id, plainText, lastEditedTime, ... }. Idempotent — safe to retry.
- update-database-itemUpdate an existing row (record) in a Notion database. Update row, modify record, change relation, set assignee, mark as done. Pass `pageId` and `properties` as a flat agent-friendly map: `{ Status: "Done", Assignee: ["<uuid>"] }`. The handler resolves the schema from the parent database and serialises each value automatically. Pass `archived: true` to move to trash. Idempotent — safe to retry. For multi-source DBs the `databaseId` of the row is read off the page parent.
- update-database-schemaAdd/modify/remove database columns and optionally rename. Schema mutations target the data source (Notion API 2025-09-03 split). Pass `dataSourceId` for multi-source DBs; otherwise the first one is used. Set a property value to `null` to remove it. Relation columns: pass `{ relation: { database_id: <id-or-url> } }` — the data_source_id and single_property envelope are resolved server-side. Returns the curated updated database { id, schema, title, description, lastEditedTime }. Idempotent per-field.
- update-pageUpdate page properties and/or archive state. Returns the curated updated page { id, url, title, properties, icon, cover, archived, lastEditedTime }. Idempotent per-field — retries are safe.
- update-page-markdownEdit a page using markdown ops. Modes: 'replace' (default — overwrites the whole body with `markdown`), 'append' (adds `markdown` at the end, optional `afterBlockId`), 'edit' (apply per-string edits via `edits: [{oldStr, newStr, replaceAll?}]`). Returns { pageId, mode }. `replace` is destructive — not retryable.
- upload-fileUpload a file to Notion. Three-step lifecycle: create → send → complete (handled internally). Provide either `dataUrl` (base64 inline) or `filePath` (server-side path). Returns { fileUploadId, status, name, contentType }. The id can be embedded in subsequent block creates as { type: 'file_upload', file_upload: { id } }. Hard cap 20 MB.
03
Auth and permissions
What it asks for.
Declared in the manifest, in advance. The app cannot reach anything it did not ask for here.
Scopes
read_contentupdate_content
System secrets
CLIENT_IDCLIENT_SECRET
User secrets
ACCESS_TOKENREFRESH_TOKENEXPIRY_DATE
Reading further
The manifest and the source for Notion live in the monorepo, alongside the other apps.