Notion-update-pageNOTION_MCP_NOTION_UPDATE_PAGE
## Overview
Update a Notion page's properties or content.
## Properties
Notion page properties are a JSON map of property names to SQLite values.
For pages in a database:
- ALWAYS use the "fetch" tool first to get the data source schema and the exact property names.
- Provide a non-null value to update a property's value.
- Omitted properties are left unchanged.
**IMPORTANT**: Some property types require specific formats:
- Date properties: Split into "date:{property}:start", "date:{property}:end" (optional), and "date:{property}:is_datetime" (0 or 1)
- Place properties: Split into "place:{property}:name", "place:{property}:address", "place:{property}:latitude", "place:{property}:longitude", and "place:{property}:google_place_id" (optional)
- Number properties: Use JavaScript numbers (not strings)
- Checkbox properties: Use "__YES__" for checked, "__NO__" for unchecked
- Relation properties: Use an array of related page URLs or page IDs, e.g. ["https://www.notion.so/26ab1f9f4c5f80b18d3bd10a6b1d2f4e", "26ab1f9f-4c5f-80b1-8d3b-d10a6b1d2f4e"]
- Files properties: Use a JSON array of file IDs, Notion Folder URLs, and/or <folder> tags copied from fetch output. Folders are stored as native Folder references, not ordinary links.
**Special property naming**: Properties named "id" or "url" (case insensitive) must be prefixed with "userDefined:" (e.g., "userDefined:URL", "userDefined:id")
For pages outside of a database:
- The only allowed property is "title", which is the title of the page in inline markdown format.
## Content
Notion page content is a string in Notion-flavored Markdown format.
**IMPORTANT**: For the complete Markdown specification, first read the MCP resource `notion://docs/enhanced-markdown-spec` through your MCP client's resource-reading interface, or call the Notion "fetch" tool with this URI if your client does not support reading MCP resources. Do NOT pass this URI to any other URL-fetching tool. Do NOT guess or hallucinate Markdown syntax.
By default, use native Notion mentions for references you add to existing Notion pages, databases, data sources, and people. Use Markdown links only for external URLs or when the user requests a plain link.
Before changing content, fetch the page unless it is already loaded for this task. Inspect the target and nearby sections. Match their heading level, block type, nesting, list or table pattern, and prose style.
Make the smallest complete edit. Prefer "update_content" for targeted search-and-replace edits, and use "insert_content" only to prepend or append. Avoid full-page "replace_content" when a targeted command is sufficient. Preserve unrelated wording, structure, order, and native references; do not broadly rewrite or improve the page unless the user asks.
For "update_content", use the smallest exact old_str from the fetched page that uniquely identifies the target. If the edit would remove material content the user did not explicitly identify, ask for confirmation first.
After a multi-part or structural content edit, fetch the page again and verify the requested content and nesting. Skip this extra read for a simple, exact edit.
### Preserving Child Pages and Databases
When using "replace_content", the operation will check if any child pages or databases would be deleted. If so, it will fail with an error listing the affected items.
To preserve child pages/databases, include them in new_str using `<page url="...">` or `<database url="...">` tags. Get the exact URLs from the "fetch" tool output.
**CRITICAL**: To intentionally delete child content: if the call failed with validation and requires `allow_deleting_content` to be true, DO NOT automatically assume the content should be deleted. ALWAYS show the list of pages to be deleted and ask for user confirmation before proceeding.
## Icon and Cover
You can set or remove a page's icon and cover alongside any command.
- "icon": An emoji character (e.g. "🚀"), a custom emoji by name (e.g. ":rocket_ship:"), or an external image URL. Use "none" to remove. Omit to leave unchanged.
- "cover": An external image URL. Use "none" to remove. Omit to leave unchanged.
- When you set an icon, keep the page title free of a duplicate leading emoji. The icon is rendered separately before the title.
## Skills
For skill creation or updates: Before creating or updating a skill, read the MCP resource `notion://docs/skills` through your MCP client's resource-reading interface. If your client does not support reading MCP resources, call the Notion "fetch" tool with this URI instead. Do NOT pass this URI to any other URL-fetching tool.
Set `is_skill` to `true` to mark the page as a skill, or `false` to remove the skill designation. This can be set alongside any command. To change only the skill status without making another page change, use the `update_properties` command and omit `properties`.
## Examples
<example description="Update page icon and cover">
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "update_properties",
"properties": {"title": "My Page"},
"icon": "🚀",
"cover": "https://example.com/cover.jpg"
}
</example>
<example description="Update page properties">
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "update_properties",
"properties": {
"title": "New Page Title",
"status": "In Progress",
"priority": 5,
"checkbox": "__YES__",
"related_tasks": ["26ab1f9f-4c5f-80b1-8d3b-d10a6b1d2f4e"],
"date:deadline:start": "2024-12-25",
"date:deadline:is_datetime": 0,
"place:office:name": "HQ",
"place:office:latitude": 37.7749,
"place:office:longitude": -122.4194
}
}
</example>
<example description="Replace the entire content of a page">
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "replace_content",
"new_str": "# New Section
Updated content goes here"
}
</example>
<example description="Update specific content in a page (search-and-replace)">
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "update_content",
"content_updates": [
{
"old_str": "# Old Section
Old content here",
"new_str": "# New Section
Updated content goes here"
}
]
}
</example>
<example description="Insert new content at the top of a page">
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "insert_content",
"content": "## Latest update
Status update goes here",
"position": { "type": "start" }
}
</example>
<example description="Insert content after a specific location">
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "update_content",
"content_updates": [
{
"old_str": "## Previous section
Existing content",
"new_str": "## Previous section
Existing content
## New Section
Content to insert goes here"
}
]
}
</example>
<example description="Multiple content updates in a single call">
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "update_content",
"content_updates": [
{
"old_str": "Old text 1",
"new_str": "New text 1"
},
{
"old_str": "Old text 2",
"new_str": "New text 2"
}
]
}
</example>
## Templates
You can apply a template to an existing page using the "apply_template" command. The template content is appended to the page asynchronously. Get template IDs from the <templates> section in the fetch tool results for a database, or use any page ID as a template.
<example description="Apply a template to an existing page">
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "apply_template",
"template_id": "a5da15f6-b853-455d-8827-f906fb52db2b"
}
</example>
## Verification
You can verify or unverify a page using the "update_verification" command. Verification marks a page as reviewed and up-to-date. Requires a Business or Enterprise plan (or the page must be in a wiki).
When updating verification, the owner will be automatically set to the authenticated actor.
<example description="Verify a page for 90 days">
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "update_verification",
"verification_status": "verified",
"verification_expiry_days": 90
}
</example>
<example description="Verify a page indefinitely">
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "update_verification",
"verification_status": "verified"
}
</example>
<example description="Remove verification from a page">
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "update_verification",
"verification_status": "unverified"
}
</example>