Notion

Search

Perform a search over: - "internal": Semantic search over your entire Notion workspace and connected sources (Slack, Google Drive, Github, Jira, Microsoft Teams, Sharepoint, OneDrive, Linear). Supports filtering by creation date and creator. - "user": Search for Notion users in the current workspace by name or email. When the user lacks Notion AI features, internal search automatically falls back to workspace search (without connected sources), indicated by type: "workspace_search" instead of "ai_search". After obtaining search results, use the "fetch" tool if you need the full contents of each page or database result. If you have the URL or ID of a Notion database you want to search within, you MUST first fetch the database using the "fetch" tool to get the data source (collection://...) URL from the <data-source url="..."> tag and then use that as the data_source_url parameter for search. If "fetch" shows the database has multiple data sources, do whichever of the following makes sense: - Use whichever data source corresponds to the view the user provided in their Notion URL, when there is a ?v=... query parameter present. - Use context from the user & data source names to identify which to use for the search - Search all data sources for the database using separate search tool calls Do NOT try to use the database URL/ID alongside the collection:// prefix for the data_source_url. Do NOT try to use a database URL as a page URL if you know from context that it's a database and not a regular page. <example description="Search with date range filter (only documents created in 2024)"> { "query": "quarterly revenue report", "query_type": "internal", "filters": { "created_date_range": { "start_date": "2024-01-01", "end_date": "2025-01-01" } } } </example> <example description="Search within teamspace, filtered by creator"> { "query": "project updates", "query_type": "internal", "teamspace_id": "f336d0bc-b841-465b-8045-024475c079dd", "filters": { "created_by_user_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"] } } </example> <example description="Search within database pages with combined filters"> { "query": "design review feedback", "query_type": "internal", "data_source_url": "collection://f336d0bc-b841-465b-8045-024475c079dd", "filters": { "created_date_range": { "start_date": "2024-10-01" }, "created_by_user_ids": ["user-id-1", "user-id-2"] } } </example> <example description="Search for users (no filters allowed)"> { "query": "john@example.com", "query_type": "user" } </example> <common-use-cases> - Find recent documents: Use created_date_range filter - Find content by specific authors: Use created_by_user_ids filter - Audit trail: Combine both filters to find who created what and when - Team member lookup: Use query_type: "user" with name/email patterns </common-use-cases>

Fetch

Retrieves details about a Notion entity by its URL or ID. You can fetch the following types of entities: - Page, i.e. from a <page> block or a <mention-page> mention - Database, i.e. from a <database> block or a <mention-database> mention Use the "fetch" tool when you need to see the details of a Notion entity you already know exists and have its URL or ID. Provide the Notion entity's URL or ID in the `id` parameter. You must make multiple calls to the "fetch" tool if you want to fetch multiple entities. Content for pages that are returned use the enhanced Markdown format, which is a superset of the standard Markdown syntax. See the full spec in the description of the "create-pages" tool. Databases can have multiple data sources, which are collections of pages with the same schema. When fetching a database, the tool will return information about all its data sources. NOTE regarding multi-source databases: If your input URL looks like: https://notion.so/workspace/26c104cd477e80059141c7ed3bce2ce6?v=26c104cd477e818ca439000c4500cf98 The UUID before the '?v=' is the database ID, and the UUID after the '?v=' is the specific view ID. All views and data sources are included in the response, but views can be associated with a specific data source, so you may be able to narrow down which data source the URL refers to based on the fetch response. Continuing the example of fetching the above URL, if the response looks like the following, then the URL is associated with the data source collection://26c104cd-477e-805f-95d7-000b4340f82f. This can be helpful if the user provides the complete URL and wants to find pages in that data source; the search tool requires a specific data source ID. <snippet description="Partial fetch response for a multi-source database"> <view url="{{view://26c104cd-477e-818c-a439-000c4500cf98}}"> {"dataSourceUrl":"{{collection://26c104cd-477e-805f-95d7-000b4340f82f}}","name":"","properties":["Name","Number"],"type":"table"} </view> </snippet> <example description="Fetch a page by URL"> {"id": "https://www.notion.so/workspace/Product-Requirements-1234567890abcdef"} </example> <example description="Fetch a page by ID (UUIDv4 with dashes)"> {"id": "12345678-90ab-cdef-1234-567890abcdef"} </example> <example description="Fetch a page by ID (UUIDv4 without dashes)"> {"id": "1234567890abcdef1234567890abcdef"} </example> <example description="Fetch a database"> {"id": "https://www.notion.so/workspace/Projects-Database-abcdef1234567890"} </example> <common-use-cases> - "What are the product requirements still need to be implemented from this ticket https://notion.so/page-url?" - "Show me the details of the project database at this URL" - "Get the content of page 12345678-90ab-cdef-1234-567890abcdef" </common-use-cases>

Create pages

## Overview Creates one or more Notion pages, with the specified properties and content. ## Parent All pages created with a single call to this tool will have the same parent. The parent can be a Notion page ("page_id") or data source ("data_source_id"). If the parent is omitted, the pages are created as standalone, workspace-level private pages, and the person that created them can organize them later as they see fit. If you have a database URL, ALWAYS pass it to the "fetch" tool first to get the schema and URLs of each data source under the database. You can't use the "database_id" parent type if the database has more than one data source, so you'll need to identify which "data_source_id" to use based on the situation and the results from the fetch tool (data source URLs look like collection://<data_source_id>). If you know the pages should be created under a data source, do NOT use the database ID or URL under the "page_id" parameter; "page_id" is only for regular, non-database pages. ## Properties Notion page properties are a JSON map of property names to SQLite values. When creating pages in a database: - Use the correct property names from the data source schema shown in the fetch tool results. - Always include a title property. Data sources always have exactly one title property, but it may not be named "title", so, again, rely on the fetched data source schema. For pages outside of a database: - The only allowed property is "title", which is the title of the page in inline markdown format. Always include a "title" property. **IMPORTANT**: Some property types require expanded 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 **Special property naming**: Properties named "id" or "url" (case insensitive) must be prefixed with "userDefined:" (e.g., "userDefined:URL", "userDefined:id") ## Examples <example description="Create a standalone page with a title and content"> { "pages": [ { "properties": {"title": "Page title"}, "content": "# Section 1 Section 1 content # Section 2 Section 2 content" } ] } </example> <example description="Create a page under a database's data source"> { "parent": {"data_source_id": "f336d0bc-b841-465b-8045-024475c079dd"}, "pages": [ { "properties": { "Task Name": "Task 123", "Status": "In Progress", "Priority": 5, "Is Complete": "__YES__", "date:Due Date:start": "2024-12-25", "date:Due Date:is_datetime": 0 } } ] } </example> <example description="Create a page with an existing page as a parent"> { "parent": {"page_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}, "pages": [ { "properties": {"title": "Page title"}, "content": "# Section 1 Section 1 content # Section 2 Section 2 content" } ] } </example> ## Content Notion page content is a string in Notion-flavored Markdown format. Don't include the page title at the top of the page's content. Only include it under "properties". Below is the full Notion-flavored Markdown specification, applicable to this create pages tool and other tools like update-page and fetch. This spec is also available as a separate MCP resource. ### Notion-flavored Markdown Notion-flavored Markdown is a variant of standard Markdown with additional features to support all Block and Rich text types. Use tabs for indentation. Use backslashes to escape characters. For example, * will render as * and not as a bold delimiter. Block types: Markdown blocks use a {color="Color"} attribute list to set a block color. Text: Rich text {color="Color"} Children Headings: # Rich text {color="Color"} ## Rich text {color="Color"} ### Rich text {color="Color"} (Headings 4, 5, and 6 are not supported in Notion and will be converted to heading 3.) Bulleted list: - Rich text {color="Color"} Children Numbered list: 1. Rich text {color="Color"} Children Bulleted and numbered list items should contain inline rich text -- otherwise they will render as empty list items, which look awkward in the Notion UI. (The inline text should be rich text -- any other block type will not be rendered inline, but as a child to an empty list item.) Rich text types: Bold: **Rich text** Italic: *Rich text* Strikethrough: ~~Rich text~~ Underline: <span underline="true">Rich text</span> Inline code: `Code` Link: [Link text](URL) Citation: [^URL] To create a citation, you can either reference a compressed URL like this,[^{{1}}] or a full URL like this.[^example.com] Colors: <span color?="Color">Rich text</span> Inline math: $Equation$ or $`Equation`$ if you want to use markdown delimiters within the equation. There must be whitespace before the starting $ symbol and after the ending $ symbol. There must not be whitespace right after the starting $ symbol or before the ending $ symbol. Inline line breaks within a block (this is mostly useful in multi-line quote or callout blocks, where an ordinary newline character should not be used since it will break up the block structure): <br> Mentions: User: <mention-user url="{{URL}}">User name</mention-user> The URL must always be provided, and refer to an existing User. But Providing the user name is optional. In the UI, the name will always be displayed. So an alternative self-closing format is also supported: <mention-user url="{{URL}}"/> Page: <mention-page url="{{URL}}">Page title</mention-page> The URL must always be provided, and refer to an existing Page. Providing the page title is optional. In the UI, the title will always be displayed. Mentioned pages can be viewed using the "view" tool. Database: <mention-database url="{{URL}}">Database name</mention-database> The URL must always be provided, and refer to an existing Database. Providing the database name is optional. In the UI, the name will always be displayed. Mentioned databases can be viewed using the "view" tool. Data source: <mention-data-source url="{{URL}}">Data source name</mention-data-source> The URL must always be provided, and refer to an existing data source. Providing the data source name is optional. In the UI, the name will always be displayed. Mentioned data sources can be viewed using the "view" tool. Date: <mention-date start="YYYY-MM-DD" end="YYYY-MM-DD"/> Datetime: <mention-date start="YYYY-MM-DDThh:mm:ssZ" end="YYYY-MM-DDThh:mm:ssZ"/> Custom emoji: :emoji_name: Custom emoji are rendered as the emoji name surrounded by colons. Colors: Text colors (colored text with transparent background): gray, brown, orange, yellow, green, blue, purple, pink, red Background colors (colored background with contrasting text): gray_bg, brown_bg, orange_bg, yellow_bg, green_bg, blue_bg, purple_bg, pink_bg, red_bg Usage: - Block colors: Add color="Color" to the first line of any block - Rich text colors (text colors and background colors are both supported): Use <span color="Color">Rich text</span> #### Advanced Block types for Page content The following block types may only be used in page content. <advanced-blocks> Quote: > Rich text {color="Color"} Children Use of a single ">" on a line without any other text should be avoided -- this will render as an empty blockquote, which is not visually appealing. To include multiple lines of text in a single blockquote, use a single > and linebreaks (not multiple > lines, which will render as multiple separate blockquotes, unlike in standard markdown): > Line 1<br>Line 2<br>Line 3 {color="Color"} To-do: - [ ] Rich text {color="Color"} Children - [x] Rich text {color="Color"} Children Toggle: ▶ Rich text {color="Color"} Children Toggle heading 1: ▶# Rich text {color="Color"} Children Toggle heading 2: ▶## Rich text {color="Color"} Children Toggle heading 3: ▶### Rich text {color="Color"} Children For toggles and toggle headings, the children must be indented in order for them to be toggleable. If you do not indent the children, they will not be contained within the toggle or toggle heading. Divider: --- Table: <table fit-page-width?="true|false" header-row?="true|false" header-column?="true|false"> <colgroup> <col color?="Color"> <col color?="Color"> </colgroup> <tr color?="Color"> <td>Data cell</td> <td color?="Color">Data cell</td> </tr> <tr> <td>Data cell</td> <td>Data cell</td> </tr> </table> Note: All table attributes are optional. If omitted, they default to false. Table structure: - <table>: Root element with optional attributes: - fit-page-width: Whether the table should fill the page width - header-row: Whether the first row is a header - header-column: Whether the first column is a header - <colgroup>: Optional element defining column-wide styles - <col>: Column definition with optional attributes: - color: The color of the column - width: The width of the column. Leave empty to auto-size. - <tr>: Table row with optional color attribute - <td>: Data cell with optional color attribute Color precedence (highest to lowest): 1. Cell color (<td color="red">) 2. Row color (<tr color="blue_bg">) 3. Column color (<col color="gray">) To format text inside of table cells, use Notion-flavored Markdown, not HTML. For instance, bold text in a table should be wrapped in **, not <strong>. Equation: $$ Equation $$ Code: ```language Code ``` XML blocks use the "color" attribute to set a block color. Callout: <callout icon?="emoji" color?="Color">Rich text</callout> To create a new line within a callout, use <br>, not a newline character. Using a newline character in a callout will cause a rendering bug. For any other formatting inside of callout blocks, use Notion-flavored Markdown, not HTML. For instance, bold text in a callout should be wrapped in **, not <strong>. Columns: <columns> <column> Children </column> <column> Children </column> </columns> Page: <page url="{{URL}}" color?="Color">Title</page> Sub-pages can be viewed using the "view" tool. To create a new sub-page, omit the URL. You can then update the page content and properties with the "update-page" tool. Example: <page>New Page</page> WARNING: Using <page> with an existing page URL will MOVE the page to a new parent page with this content. If moving is not intended use the <mention-page> block instead. Database: <database url="{{URL}}" inline?="{true|false}" icon?="Emoji" color?="Color">Title</database> To create a new database, omit the URL. You can then update the database properties and content with the "update-database" tool. Example: <database>New Database</database> The "inline" toggles how the database is displayed in the UI. If it is true, the database is fully visible and interactive on the page. If false, the database is displayed as a sub-page. There is no "Data Source" block type. Data Sources are always inside a Database, and only Databases can be inserted into a Page. WARNING: Using <database> with an existing database URL will MOVE the database to a new parent page with this content. If moving is not intended use the <mention-database> block instead. Audio: <audio source="{{URL}}" color?="Color">Caption</audio> File: File content can be viewed using the "view" tool. <file source="{{URL}}" color?="Color">Caption</file> Image: Image content can be viewed using the "view" tool. <image source="{{URL}}" color?="Color">Caption</image> PDF: PDF content can be viewed using the "view" tool. <pdf source="{{URL}}" color?="Color">Caption</pdf> Video: <video source="{{URL}}" color?="Color">Caption</video> (Note that source URLs can either be compressed URLs, such as source="{{1}}", or full URLs, such as source="example.com". Full URLs enclosed in curly brackets, like source="{{https://example.com}}" or source="{{example.com}}", do not work.) Table of contents: <table_of_contents color?="Color"/> Synced block: The original source for a synced block. When creating a new synced block, do not provide the URL. After inserting the synced block into a page, the URL will be provided. <synced_block url?="{{URL}}"> Children </synced_block> Note: When creating new synced blocks, omit the url attribute - it will be auto-generated. When reading existing synced blocks, the url attribute will be present. Synced block reference: A reference to a synced block. The synced block must already exist and url must be provided. You can directly update the children of the synced block reference and it will update both the original synced block and the synced block reference. <synced_block_reference url="{{URL}}"> Children </synced_block_reference> Meeting notes: <meeting-notes> Rich text (meeting title) <summary> AI-generated summary of the notes + transcript </summary> <notes> User notes </notes> <transcript> Transcript of the audio (cannot be edited) </transcript> </meeting-notes> Note: The <transcript> tag contains a raw transcript and cannot be edited. If you are creating a new meeting notes block, do not include <transcript> tags -- attempting to do so will result in an error. Unknown (a block type that is not supported in the API yet): <unknown url="{{URL}}" alt="Alt"/> </advanced-blocks>

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 expanded 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 **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. See the "create-pages" tool description for the full enhanced Markdown spec. Before updating a page's content with this tool, use the "fetch" tool first to get the existing content to find out the Markdown snippets to use in the "replace_content_range" or "insert_content_after" commands. ## Examples <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__", "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="Replace specific content in a page"> { "page_id": "f336d0bc-b841-465b-8045-024475c079dd", "command": "replace_content_range", "selection_with_ellipsis": "# Old Section...end of section", "new_str": "# New Section Updated content goes here" } </example> <example description="Insert content after specific text"> { "page_id": "f336d0bc-b841-465b-8045-024475c079dd", "command": "insert_content_after", "selection_with_ellipsis": "## Previous section...", "new_str": " ## New Section Content to insert goes here" } </example> **Note**: For selection_with_ellipsis, provide only the first ~10 characters, an ellipsis, and the last ~10 characters. Ensure the selection is unique; use longer snippets if needed to avoid ambiguity.

Move pages

Move one or more Notion pages or databases to a new parent.

Duplicate page

Duplicate a Notion page. The page must be within the current workspace, and you must have permission to access it. The duplication completes asynchronously, so do not rely on the new page identified by the returned ID or URL to be populated immediately. Let the user know that the duplication is in progress and that they can check back later using the 'fetch' tool or by clicking the returned URL and viewing it in the Notion app.

Create database

Creates a new Notion database with the specified properties. Use this tool when you need to create a new database that doesn't exist yet. The database schema is defined through the "properties" object. If no title property is provided, one will be automatically added with the name "Name". Each property should include a type and may have additional configuration based on the property type. Common property types: - title: The main property (required, cannot be deleted) - rich_text: Multi-line text - number: Numeric values with optional formatting - select: Single choice from options - multi_select: Multiple choices from options - date: Date with optional time - people: User references - checkbox: Boolean values - url: Web links - email: Email addresses - phone_number: Phone numbers - formula: Calculated values based on other properties - relation: Links to pages in another database - rollup: Aggregated values from related pages The tool returns a rendered Markdown representation of the created database including its structure, data source configuration with full schema details, and SQLite table definition. This provides complete visibility into the database that was created. Examples of creating databases: 1. Create a minimal database with auto-added title property: { "properties": {} } 2. Create a task database under a page: { "parent": {"page_id": "f336d0bc-b841-465b-8045-024475c079dd"}, "title": [{"text": {"content": "Project Tasks"}}], "properties": { "Status": { "type": "select", "select": { "options": [ {"name": "To Do", "color": "red"}, {"name": "In Progress", "color": "yellow"}, {"name": "Done", "color": "green"} ] } }, "Priority": { "type": "select", "select": { "options": [ {"name": "High", "color": "red"}, {"name": "Medium", "color": "yellow"}, {"name": "Low", "color": "green"} ] } }, "Due Date": {"type": "date", "date": {}}, "Assignee": {"type": "people", "people": {}} } } 3. Create a workspace-level database with various property types: { "title": [{"text": {"content": "Company Directory"}}], "properties": { "Name": {"type": "title", "title": {}}, "Email": {"type": "email", "email": {}}, "Phone": {"type": "phone_number", "phone_number": {}}, "Department": { "type": "select", "select": { "options": [ {"name": "Engineering", "color": "blue"}, {"name": "Sales", "color": "green"}, {"name": "Marketing", "color": "purple"} ] } }, "Start Date": {"type": "date", "date": {}}, "Is Active": {"type": "checkbox", "checkbox": {}}, "Notes": {"type": "rich_text", "rich_text": {}} } } 4. Create a database with relations (assuming target database exists): { "title": [{"text": {"content": "Tasks"}}], "properties": { "Project": { "type": "relation", "relation": { "database_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "single_property", "single_property": {} } } } }

Update database

Update a Notion database's properties, name, description, or other attributes. The tool returns a rendered Markdown string showing the updated database structure, including its properties, data sources, and schema information. Database properties define the columns/fields that pages in the database can have. Each property has a type (text, number, select, etc.) and configuration options. Examples: (1) Update database title and description: { "database_id": "f336d0bc-b841-465b-8045-024475c079dd", "title": [{"type": "text", "text": {"content": "Project Tracker 2024"}}], "description": [{"type": "text", "text": {"content": "Track all projects and deliverables"}}] } (2) Add new properties to a database: { "database_id": "f336d0bc-b841-465b-8045-024475c079dd", "properties": { "Priority": { "select": { "options": [ {"name": "High", "color": "red"}, {"name": "Medium", "color": "yellow"}, {"name": "Low", "color": "green"} ] } }, "Due Date": {"date": {}}, "Assigned To": {"people": {}} } } (3) Rename an existing property (use the property ID or current name): { "database_id": "f336d0bc-b841-465b-8045-024475c079dd", "properties": { "Status": {"name": "Project Status"} } } (4) Remove a property (set to null): { "database_id": "f336d0bc-b841-465b-8045-024475c079dd", "properties": { "Old Property": null } } (5) Change display mode from inline to full page: { "database_id": "f336d0bc-b841-465b-8045-024475c079dd", "is_inline": false } (6) Move database to trash (WARNING: cannot be undone without going to the Notion app UI so explicitly confirm with the user that they really want to do this): { "database_id": "f336d0bc-b841-465b-8045-024475c079dd", "in_trash": true } Common property types: - title: The main property (required, cannot be deleted) - rich_text: Multi-line text - number: Numeric values with optional formatting - select: Single choice from options - multi_select: Multiple choices from options - date: Date with optional time - people: User references - checkbox: Boolean values - url: Web links - email: Email addresses - phone_number: Phone numbers - formula: Calculated values based on other properties - relation: Links to pages in another database - rollup: Aggregated values from related pages Notes: - You cannot delete or create new title properties - A database can only have one unique_id property - Synced databases cannot be updated - Use the "fetch" tool first to see the current database schema

Create comment

Add a comment to a page

Get comments

Get all comments of a page

Get teams

Retrieves a list of teams (teamspaces) in the current workspace. This tool provides visibility into the teams that exist and whether the authenticated user is a member of each team. Includes IDs, names, and the user's role in each team. Teams are returned split by membership status and limited to a maximum of 10 results. <examples> 1. List all teams (up to the limit of each type): {} 2. Search for teams by name: {"query": "engineering"} 3. Find a specific team: {"query": "Product Design"} </examples>

Get users

List all users

Get self

Retrieve your token's bot user

Get user

Retrieve a user