Notion
Notion MCP Server
Retrieve the list of 15 available tools from Notion. Tools: notion-search, notion-fetch, notion-create-pages, notion-update-page, notion-move-pages, notion-duplicate-page, notion-create-database, notion-update-database, notion-create-comment, notion-get-comments, notion-get-teams, notion-get-users, notion-list-agents, notion-get-self, notion-get-user
OAuth2 access token for authenticated requests
List of available tools
Unauthorized
Forbidden - User doesn't have access to this server
MCP server not found
Perform a search over:
"internal": Semantic search over 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 users by name or email.
Falls back to "workspace_search" (no connected sources) when user lacks Notion AI. Use "fetch" tool for full page/database contents after getting search results. To search within a database: First fetch the database to get the data source URL (collection://...) from tags, then use that as data_source_url. For multi-source databases, match by view ID (?v=...) in URL or search all sources separately. Don't combine database URL/ID with collection:// prefix for data_source_url. Don't use database URL as page_url. { "query": "quarterly revenue report", "query_type": "internal", "filters": { "created_date_range": { "start_date": "2024-01-01", "end_date": "2025-01-01" } } } {"query": "project updates", "query_type": "internal", "teamspace_id": "f336d0bc-b841-465b-8045-024475c079dd", "filters": {"created_by_user_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]}} {"query": "design review", "data_source_url": "collection://f336d0bc-b841-465b-8045-024475c079dd", "filters": {"created_date_range": {"start_date": "2024-10-01"}, "created_by_user_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b2c3d4e5-f6a7-8901-bcde-f12345678901"]}} {"query": "[email protected]", "query_type": "user"}
Arguments:
'query' (required): Semantic search query over your entire Notion workspace and connected sources (Slack, Google Drive, Github, Jira, Microsoft Teams, Sharepoint, OneDrive, or Linear). For best results, don't provide more than one question per tool call. Use a separate "search" tool call for each search you want to perform. Alternatively, the query can be a substring or keyword to find users by matching against their name or email address. For example: "john" or "[email protected]"
'query_type': string
'data_source_url': Optionally, provide the URL of a Data source to search. This will perform a semantic search over the pages in the Data Source. Note: must be a Data Source, not a Database. tags are part of the Notion flavored Markdown format returned by tools like fetch. The full spec is available in the create-pages tool description.
'page_url': Optionally, provide the URL or ID of a page to search within. This will perform a semantic search over the content within and under the specified page. Accepts either a full page URL (e.g. https://notion.so/workspace/Page-Title-1234567890) or just the page ID (UUIDv4) with or without dashes.
'teamspace_id': Optionally, provide the ID of a teamspace to restrict search results to. This will perform a search over content within the specified teamspace only. Accepts the teamspace ID (UUIDv4) with or without dashes.
'filters': Optionally provide filters to apply to the search results. Only valid when query_type is 'internal'.
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Retrieves details about a Notion entity (page or database) by URL or ID. Provide URL or ID in 'id' parameter. Make multiple calls to fetch multiple entities. Pages use enhanced Markdown format (see "create-pages" tool for spec). Databases return all data sources (collections of pages with same schema). For multi-source databases with URLs like notion.so/db-id?v=view-id, the view ID helps identify which data source to use (check response for view's dataSourceUrl). {"id": "https://notion.so/workspace/Page-a1b2c3d4e5f67890"} {"id": "12345678-90ab-cdef-1234-567890abcdef"}
Arguments:
'id' (required): The ID or URL of the Notion page to fetch
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
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
Section 1 content
Section 2
Section 2 content" } ] } { "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 } } ] } { "parent": {"page_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}, "pages": [ { "properties": {"title": "Page title"}, "content": "# Section 1 Section 1 content
Section 2
Section 2 content" } ] }
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. If you want to add an empty line, you should explicitly output "" on its own line. Do not output on a line with other text as it will not be rendered correctly. Other empty lines will be ignored. Notion renders blocks with appropriate spacing, only add additional empty lines for extra spacing. Use backslashes to escape characters. For example, * will render as * and not as a bold delimiter. These are the characters that should be escaped: * ~ ' ＄ [ ] < > { } | ^ 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:
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: Rich text Inline code: 'Code' Link: Link text 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 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 blocks, where an ordinary newline character should not be used since it will break up the block structure):
Mentions: User: User name 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: Page: Page title 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 "fetch" tool. Database: Database name 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 "fetch" tool. Data source: Data source name 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 "fetch" tool. Date: Datetime: 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 Rich text
Advanced Block types for Page content
The following block types may only be used in page content. 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 Line 2 Line 3 {color="Color"} To-do:
Table:
Data cell
Data cell
Note: All table attributes are optional. If omitted, they default to false. Table structure: - : 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 - : Optional element defining column-wide styles. Do not include a element if you do not want to set any column colors or widths. - : Column definition with optional attributes: - color: The color of the column - width: The width of the column. Leave empty to auto-size. - : Table row with optional color attribute - ) 3. Column color () 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 . Equation: ＄＄ Equation ＄＄ Code: '''language Code ''' XML blocks use the "color" attribute to set a block color. Callout: Rich text Children Callouts can contain multiple blocks and nested children, not just inline rich text. Each child block should be indented. For any formatting inside of callout blocks, use Notion-flavored Markdown, not HTML. For instance, bold text in a callout should be wrapped in **, not . Columns: Children Children Page: Title Sub-pages can be viewed using the "fetch" 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: New Page WARNING: Using with an existing page URL will MOVE the page to a new parent page with this content. If moving is not intended use the block instead. Database: Title Provide either url or data-source-url attribute: - If "url" is an existing database URL it here will MOVE that database into the current page. If you just want to mention an existing database, use instead. - If "data-source-url" is an existing data source URL, creates a linked database view. To create a new database, omit both url and data-source-url. Example: New Database After creating a new or linked database, you can add filters, sorts, groups, or other view configuration with the "update-database" tool using the url of the newly added database. The "inline" attribute 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. Audio: Caption File: File content can be viewed using the "fetch" tool. Caption Image: Image content can be viewed using the "fetch" tool. Caption PDF: PDF content can be viewed using the "fetch" tool. Caption Video: Caption (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: 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. Children 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. Children Meeting notes: Rich text (meeting title)AI-generated summary of the notes + transcriptUser notes Transcript of the audio (cannot be edited) - The tag contains a raw transcript and cannot be edited by AI, but it can be edited by a user. - When creating new meeting notes blocks, you must omit theand tags. - Only include in a new meeting notes block if the user is SPECIFICALLY requesting note content. - Attempting to include or edit will result in an error. - All content within, , and tags must be indented at least one level deeper than the tag. Unknown (a block type that is not supported in the API yet):Arguments:'pages' (required): The pages to create.'parent': The parent under which the new pages will be created. This can be a page (page_id), a database page (database_id), or a data source/collection under a database (data_source_id). If omitted, the new pages will be created as private pages at the workspace level. Use data_source_id when you have a collection:// URL from the fetch tool.
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
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
Updated content goes here" } { "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" } { "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" } 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.
Arguments:
'data' (required): The data required for updating a page
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Move one or more Notion pages or databases to a new parent.
Arguments:
'page_or_database_ids' (required): An array of up to 100 page or database IDs to move. IDs are v4 UUIDs and can be supplied with or without dashes (e.g. extracted from a or URL given by the "search" or "fetch" tool). Data Sources under Databases can't be moved individually.
'new_parent' (required): The new parent under which the pages will be moved. This can be a page, the workspace, a database, or a specific data source under a database when there are multiple. Moving pages to the workspace level adds them as private pages and should rarely be used.
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
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.
Arguments:
'page_id' (required): The ID of the page to duplicate. This is a v4 UUID, with or without dashes, and can be parsed from a Notion page URL.
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Creates a new Notion database with the specified properties schema. If no title property provided, "Name" is auto-added. Returns Markdown with schema and SQLite definition. Property types: title (required), rich_text, number, select, multi_select, date, people, checkbox, url, email, phone_number, formula, relation, rollup.
<example description="Minimal">{"properties": {}}</example>
<example description="Task DB">{"parent": {"page_id": "f336d0bc-b841-465b-8045-024475c079dd"}, "title": [{"text": {"content": "Tasks"}}], "properties": {"Status": {"type": "select", "select": {"options": [{"name": "To Do", "color": "red"}, {"name": "Done", "color": "green"}]}}, "Due Date": {"type": "date", "date": {}}}}</example>Arguments:
'properties' (required): The property schema of the new database. If no title property is provided, one will be automatically added.
'parent': The parent under which to create the new database. If omitted, the database will be created as a private page at the workspace level.
'title': The title of the new database, as a rich text object.
'description': The description of the new database, as a rich text object.
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Update a Notion database's properties, name, description, or other attributes. Returns Markdown showing updated structure and schema. Database properties define columns/fields. See create_database for property types. 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 to trash (DANGER: confirm with user, cannot undo without Notion UI): {"database_id": "f336d0bc-b841-465b-8045-024475c079dd", "in_trash": true} Notes: Cannot delete/create title properties. Max one unique_id property. Cannot update synced databases. Use "fetch" first to see current schema.
Arguments:
'database_id' (required): The ID of the database to update. This is a UUID v4, with or without dashes, and can be parsed from a database URL.
'title': The new title of the database, as a rich text object, if you want to update it.
'description': The new description of the database, as a rich text object, if you want to update it.
'properties': Updates to make to the database's schema. Use null to remove a property, or provide the 'name' only to rename a property.
'is_inline': boolean
'in_trash': boolean
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Add a comment to a page
Arguments:
'parent' (required): The parent of the comment. This must be a page.
'rich_text' (required): An array of rich text objects that represent the content of the comment.
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Get all comments of a page
Arguments:
'page_id' (required): Identifier for a Notion page.
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Retrieves a list of teams (teamspaces) in the current workspace. Shows which teams exist, user membership status, IDs, names, and roles. Teams are returned split by membership status and limited to a maximum of 10 results.
List all teams (up to the limit of each type): {}
Search for teams by name: {"query": "engineering"}
Find a specific team: {"query": "Product Design"}
Arguments:
'query': Optional search query to filter teams by name (case-insensitive).
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Retrieves a list of users in the current workspace. Shows workspace members and guests with their IDs, names, emails (if available), and types (person or bot). Supports cursor-based pagination to iterate through all users in the workspace.
List all users (first page): {}
Search for users by name or email: {"query": "john"}
Get next page of results: {"start_cursor": "abc123"}
Set custom page size: {"page_size": 20}
Arguments:
'query': Optional search query to filter users by name or email (case-insensitive).
'start_cursor': Cursor for pagination. Use the next_cursor value from the previous response to get the next page.
'page_size': Number of users to return per page (default: 100, max: 100).
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Retrieves a list of all custom agents (workflows) that the authenticated user has access to in the current workspace. This tool provides visibility into available agents including their names, IDs, descriptions, and system instructions. The returned data includes:
Agent ID (for use with the chat tool)
Agent name
Agent description
Agent system instructions
1. List all available agents: {} 2. Search for agents by name or description: {"query": "customer support"} 3. Find agents related to a specific topic: {"query": "data analysis"}
Arguments:
'query': Optional search query to filter agents by name or description (case-insensitive).
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Retrieve your token's bot user
Arguments:
OAuth2 access token for authenticated requests
Input parameters for notion-get-self
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Retrieve a user
Arguments:
'path' (required): object
OAuth2 access token for authenticated requests
Tool execution result
Bad Request - Invalid tool arguments
Unauthorized
Forbidden - User doesn't have access to this server
MCP server or tool not found
Last updated