io.github.ai-aviate/better-notion

Add or read comments on a Notion page. ## Read comments comment({ page: "abc123" }) Returns all comments on the page as a Markdown list. ## Add a comment comment({ page: "abc123", body: "Looks good! Ready to ship." }) Adds a comment to the page. You can use the page name, ID, or URL.

Archive (soft-delete) a Notion page. The page is moved to Trash and can be restored from Notion's UI. This does NOT permanently delete the page.

List database records as a Markdown table, or list child pages of a page. For databases: returns a table with properties as columns. For pages: returns a numbered list of child pages. You can pass a database/page name (resolved via search) or an ID/URL. ## Filter syntax (databases only) Simple expressions matched against DB property names and types: - "Status is Done" → select/status equals - "Priority = High" → select equals - "Tags contains backend" → multi_select contains - "Done is true" → checkbox equals - "Due Date after 2026-03-01" → date after - "Score > 80" → number greater_than - "Name contains API" → title/rich_text contains Multiple filters: separate with " AND " (e.g. "Status is Done AND Priority is High") ## Sort syntax (databases only) - "Due Date ascending" or "Due Date asc" - "Created descending" or "Created desc" ## Example output # Task Board (24 items) | Name | Status | Due Date | |---|---|---| | Fix login bug | In Progress | 2026-03-01 |

Move a Notion page to a different parent page or database. The page keeps its content and properties; only the location changes. Example: move a page into an "Archive" page, or move a task into a different database.

Read a Notion page and return it as Markdown with YAML frontmatter. Returns frontmatter fields: - id, url: page identifiers - title: page title - parent / database: parent page ID or database ID - icon, cover: emoji or image URL - properties: database properties (if the page belongs to a database) - created, last_edited: timestamps (read-only) The body contains the page content as standard Markdown. The output can be edited and passed directly to the "write" tool to update the page. Use "depth" to include child pages in a single call (default: 1 = current page only, 2 = include children, 3 = include grandchildren). Example output: --- id: abc123-def456 title: Weekly Review database: task-db-id properties: Status: In Progress Tags: - backend --- ## Notes - Completed API design

View or modify database schema (columns/properties). ## Actions ### "list" (default) — View current schema schema({ database: "Task Board" }) Returns: property names, types, and select/multi_select options. ### "add" — Add a new property schema({ database: "Task Board", action: "add", property: "Priority", type: "select", options: ["Low", "Medium", "High"] }) ### "remove" — Remove a property schema({ database: "Task Board", action: "remove", property: "Old Column" }) ### "rename" — Rename a property schema({ database: "Task Board", action: "rename", property: "Due", name: "Due Date" }) ## Supported types for add title, rich_text, number, select, multi_select, date, checkbox, url, email, phone_number, status, people, files For select/multi_select, you can provide initial options.

Search the Notion workspace by title keyword. Returns a Markdown list with page/database IDs, titles, and metadata. Use the returned IDs with other tools: read (to get full content), write (to update), list (to query a database), delete, or move. Example output: # Search results: "MCP" (2 results) 1. **MCP Design Doc** (📝 page) - ID: `abc123` - Last edited: 2026-02-19 2. **Task Board** (database) - ID: `def456`

Quickly update page properties without rewriting content. Much simpler than the write tool for property-only changes. The page content (blocks) is never touched — only properties are updated. ## Parameters - page: Page ID, URL, or name - properties: Key-value object of properties to set ## Examples Update a single property: update({ page: "abc123", properties: { "Status": "Done" } }) Update multiple properties: update({ page: "My Task", properties: { "Status": "Done", "Priority": "High", "Due Date": "2026-03-01" } }) Supported value types: - Text: "value" - Number: 42 - Checkbox: true / false - Date: "2026-03-01" - Date range: "2026-03-01 to 2026-03-15" - Select/Status: "Option Name" - Multi-select: ["tag1", "tag2"] - URL: "https://..."

Create or update Notion pages from Markdown with YAML frontmatter. Mode (default "auto"): if frontmatter has "id" → update, otherwise → create. ## Batch mode Separate multiple pages with a line containing only "===" to create/update them in one call. ## Frontmatter fields | Field | Create | Update | Description | |-------|--------|--------|-------------| | id | - | required | Page ID to update | | title | recommended | optional | Page title | | parent | required* | ignored | Parent page name or ID | | database | required* | ignored | Database name or ID (*either parent or database) | | icon | optional | optional | Emoji (e.g. 📋) or image URL | | cover | optional | optional | Cover image URL | | properties | optional | optional | DB properties (see below) | Properties are auto-matched to the database schema. Use the exact property name as key. Read-only fields from read output (url, created, last_edited, formula, etc.) are safely ignored. ## Examples ### Create a page under a parent page: ``` --- title: Meeting Notes parent: "Project Alpha" icon: "📝" --- ## Agenda - Review progress ``` ### Create a database entry: ``` --- title: Fix login bug database: "Task Board" properties: Status: In Progress Tags: - backend - urgent Due Date: "2026-03-01" --- ## Description Login fails when password contains special chars. ``` ### Update an existing page (edit output from read): ``` --- id: abc123-def456 title: Updated Title properties: Status: Done --- ## New content Body replaces all existing blocks. ``` ### Append to an existing page (add content without rewriting): Use position: "append" to add content to the end, or "prepend" to add to the beginning. Only the new content needs to be provided — existing content is preserved. ``` --- id: abc123-def456 --- ## New section added at the end ``` ### Batch create (multiple pages in one call): ``` --- title: Task 1 database: "Task Board" properties: Status: Todo --- Task 1 details === --- title: Task…