Page CRUD for individual pages and database rows.

Actions (required params -> optional):

• create (parent_id -> title, content, properties, icon, cover)

• get (page_id): returns markdown content

• get_property (page_id, property_id)

• update (page_id -> title, content, append_content, properties, icon, cover, archived)

• move (page_id, parent_id)

• archive (page_id) / restore (page_id)

• duplicate (page_id -> parent_id)

Use databases instead for querying or bulk row operations. Property format: simple values auto-convert -- string for title/rich_text/select/status, number for number, boolean for checkbox, string[] for multi_select, ISO date "2025-01-15" for date. Example: properties: {"Name": "My Page", "Status": "In Progress", "Tags": ["tag1", "tag2"], "Due": "2025-06-01", "Count": 42, "Done": true}.

Database schema, query, and bulk row operations.

Actions (required params -> optional):

• create (parent_id -> title, properties, is_inline, icon, cover)

• get (database_id)

• query (database_id -> filters, sorts, limit, search)

• create_page (database_id, pages[{properties}])

• update_page (database_id, page_id, page_properties)

• delete_page (database_id, page_ids)

• create_data_source / update_data_source / update_database / list_templates

Use pages instead for single page CRUD. Accepts both database_id (from URL) and data_source_id (from workspace search) -- auto-resolved.

Read and modify block-level content within pages.

Actions (required params -> optional):

• get (block_id): retrieve single block

• children (block_id): list child blocks

• append (block_id, content -> position, after_block_id): add markdown content at position

• update (block_id, content): replace text block content

• delete (block_id): remove block

Use pages for page metadata/properties. Page IDs are valid block IDs. update only works on text blocks (paragraph, headings, lists, quote, to_do, code). Image/file blocks contain signed URLs (1h expiry). append supports position: "start" (prepend), "end" (default), "after_block" (requires after_block_id).

Get user information.

Actions (required params):

• list: all workspace users (requires admin permissions)

• get (user_id): single user info

• me: current bot/integration user

• from_workspace: extract users from accessible pages (use if list fails)

Search workspace and get workspace info.

Actions (required params -> optional):

• info: workspace name, plan, and bot user

• search (-> query, filter.object="page"|"data_source", sort, limit): find pages/databases shared with integration

Manage page comments.

Actions (required params -> optional):

• list (page_id): all comments on a page

• get (comment_id): single comment

• create (content -> page_id for new discussion, discussion_id for reply)

Convert between markdown and Notion block JSON. Directions: markdown-to-blocks (input: markdown string), blocks-to-markdown (input: JSON array of Notion blocks or JSON string). Most tools (pages, blocks) handle markdown automatically -- use this only for preview/validation. Supported markdown: headings, lists, to-do, code blocks, blockquotes, dividers, callouts (> [!NOTE]), toggles (), tables, images, bookmarks, embeds, equations ($$), columns (:::columns), [toc], [breadcrumb]. Inline: bold, italic, code, strike, link.

Upload files to Notion.

Actions (required params -> optional):

• create (filename -> content_type, mode="single"|"multi_part", number_of_parts)

• send (file_upload_id, file_content -> part_number): base64-encoded content

• complete (file_upload_id)

• retrieve (file_upload_id)

• list (-> limit)

Max 20MB direct, multi-part for larger files.

Get full documentation for a tool. Use when compressed descriptions are insufficient.

Manage server configuration and credential state.

Actions:

• status: current credential state, token source, setup URL

• setup_start (-> force): trigger relay setup to configure Notion token via browser

• setup_reset: clear credentials and config, return to awaiting_setup

• setup_complete: re-check credentials after external config changes

• set: update a runtime setting (notion has no mutable settings; returns info)

• cache_clear: clear any cached state (no-op for notion)

Open the relay configuration form for better-notion-mcp in the user browser. Returns the relay URL, whether the browser launched, and the current credential state. Auto-respawns the daemon if it has died.