Better Notion MCP

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).

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)

Manage server configuration and credential state.

Actions:

• status: current credential state, token source, setup URL
• setup_status: credential/setup state only (alias-equivalent to status for notion; kept for cross-server parity)
• 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.

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 (<details>), tables, images, bookmarks, embeds, equations ($$), columns (:::columns), [toc], [breadcrumb]. Inline: bold, *italic*, code, ~~strike~~, [link](url).

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.

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.

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}.

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