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

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

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 2
database: "Task Board"
properties:
  Status: Todo
---
Task 2 details

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

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)

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.

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.

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://..."

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.

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.