Skip to main content
Notion MCP provides tools for searching, reading, and changing content in your Notion workspace. An MCP client can call several tools in one task. For example, it can search for pages, create a page from the results, and then update page properties.

​
MCP tools

notion-searchSearch Notion and connected apps like Slack, Google Drive, and Jira. In Notion, narrow results by location (page, data source, or teamspace), creator or editor, date, title, or content status. You can also sort results, search with filters only, and return up to 50 results.Results may include path and verification details. Fetch important matches before relying on them.
  • Searching connected apps requires Notion AI.
  • Full Notion MCP on Business or Enterprise is required to filter by editor, last-edited date, multiple teamspaces, title only, or content status, and to sort by date. Other filters are available on every plan.
Example prompts:
  • “Check Slack for how we solved this bug in the past”
  • “Search for documents mentioning ‘budget approval process’”
  • “Look for meeting notes from last week with John”
  • “Find all project pages that mention ‘ready for dev’”
notion-search-skillsFinds active Notion Skills that the connected user can access. Pass a Skill name or a short description of the task, or omit the query to list up to 10 recent Skills. Results contain compact metadata; fetch the selected Skill’s URL before following its instructions.Example prompts:
  • “Find my usual workflow for preparing a customer briefing”
  • “What reusable workflows do I have for code review?”
  • “Use my weekly project update Skill”
notion-fetchRetrieves content from a Notion page, database, data source, or saved database view by its URL or ID. You can pass a data source ID (from collection://... tags in database responses) to fetch details about that specific data source, including its schema and properties. When fetching a database, the response includes available templates for each data source, which can be used with the create-pages and update-page tools.Fetched pages include path, page_last_edited_at, and, when available, verification.state and verification.expires_at. These fields help distinguish pages with similar titles and identify sources that Notion marks as verified.Fetched pages, including database items, include cover separately from database properties. It is null when there is no cover. Otherwise, it uses the REST API’s file object shape: type: "external" with external.url for linked or Notion gallery images, or type: "file" with file.url and file.expiry_time for uploaded images.MCP’s signed cover URLs expire after five minutes; the REST API uses one hour. Re-fetching the page returns a fresh URL. An omitted cover means the metadata is unavailable or not applicable, not that the page has no cover.Fetched pages, including database items, also include icon. It is null when there is no icon. Otherwise, it uses the REST API’s emoji and icon object shapes: type: "emoji" with emoji, type: "custom_emoji" with custom_emoji.id, custom_emoji.name, and custom_emoji.url, or type: "icon" with icon.name and icon.color for a native Notion icon. Image icons use the file object shape: type: "external" with external.url, or type: "file" with file.url and file.expiry_time for an image uploaded to Notion.Signed icon URLs expire after five minutes, the same as cover URLs, and re-fetching the page returns a fresh URL. An omitted icon means the metadata is unavailable or not applicable, not that the page has no icon. The icon field is read-only. To set or change an icon, pass the icon string that notion-create-pages and notion-update-page accept.Pass a view:// URL from a database response to read a saved view’s filters, sorts, and display settings. A database URL with a ?v= parameter still returns the database. To read the rows shown by a view, use notion-query-data-sources with mode: "view".Pass the special id self to retrieve the connected workspace and user identity instead of an entity. The response includes a self object with the workspace’s ID and name, and the authenticated user’s ID, name, type, and email — useful for labeling a connection after OAuth.The self object also includes current_tool_access, a map of tool names to their access state on this workspace’s plan: available, available_with_limit (calls can be made up to the limit included with the workspace’s plan), upgrade_required (calls return an upgrade prompt, and the map entry carries an upgrade_url), or not_enabled. Tools are listed on every plan, so consult this map to route away from tools that would only return an upgrade prompt. The map covers the tools in a current tool list, so a tool that is no longer advertised has no entry, even when a cached tool list can still call it. For query_data_sources, view mode is always available; Business and Enterprise plans with Notion AI can query any number of data sources, while other plans receive metered single-data-source access. Keys are the tools’ base names; when tools appear with a notion- prefix and hyphens (e.g. notion-query-data-sources), they correspond to the map key with the prefix dropped and hyphens as underscores (query_data_sources).When a page is large enough that some subtrees could not be loaded, the response sets truncated to true and includes unknown_block_ids (up to 50 omitted subtree root IDs) and unknown_block_count (the total number of omitted subtree roots). Pass one of the returned IDs back to notion-fetch to retrieve that subtree directly. An ID may also represent content the caller cannot access, so treat an object_not_found error on retry as a permissions signal rather than a failure to handle.Example prompts:
  • “What product requirements still need to be implemented from this ticket https://notion.com/page-url?”
  • “Fetch the data source collection://f336d0bc-b841-465b-8045-024475c079dd to see its schema”
  • “Fetch the view view://8ac3f3d0-1f2b-4c7e-9d51-4b0c0a9f2e77 to see how it’s filtered and sorted”
  • “Fetch the bug tracking database so I can see the available templates”
  • “Fetch self to see which workspace and user this connection is for”
notion-create-file-uploadCreates a short-lived URL for uploading one local file directly to Notion. After calling the tool, the MCP client sends the file as a multipart/form-data POST request using the returned URL, headers, and form field. The upload response includes suggested_markdown, which can be passed directly to notion-create-pages or notion-update-page, or included on a separate line in notion-create-comment markdown to attach the file.Files are limited to 20 MiB for this single-part upload flow, and workspace file-size limits still apply. For larger files, use the file upload API.Example prompts:
  • “Upload diagram.png and add it to the project plan”
  • “Attach report.pdf to a new page”
  • “Upload this file and include it in my comment”
notion-create-attachmentCreates a Notion attachment from exactly one source: inline UTF-8 text, a file at a direct public HTTPS URL, or a completed file upload created by the same integration. The result includes suggested_markdown, which can be passed directly to notion-create-pages or notion-update-page, or included on a separate line in notion-create-comment markdown to attach the file.Inline content supports text formats such as HTML, Markdown, CSV, JSON, and SVG, up to 200 KiB. URL downloads support binary files, must complete within one minute, and are limited to 5 MiB on free workspaces or 50 MiB on paid workspaces. URLs must not redirect, require request headers or cookies, or resolve to a private network address. For local files, use notion-create-file-upload when available. For files that exceed these limits or downloads that require redirects or authentication, use the file upload API and pass the resulting upload ID as source_file_id.Example prompts:
  • “Create an HTML attachment from this report and add it to the project page”
  • “Attach the PDF at this direct download URL to my meeting notes”
  • “Add the file I just uploaded to a comment”
notion-download-attachmentDownloads the complete UTF-8 text content of an attachment created by notion-create-attachment. Pass the file_upload_id returned when the attachment was created. The attachment must belong to the same integration, have completed uploading, and use a supported text format such as HTML, Markdown, plain text, CSV, JSON, XML, CSS, YAML, TSV, calendar, GPX, or SVG.Downloads are limited to 200 KiB. This tool does not fetch arbitrary URLs or return binary files. For larger or binary attachments, use the signed file URL returned when reading the page that contains the attachment.Example prompts:
  • “Download the HTML attachment I just created so I can edit it”
  • “Read the contents of this Markdown attachment”
  • “Retrieve the text attachment with this file upload ID”
notion-create-pagesCreates one or more Notion pages with specified properties and content. Supports applying database templates to pre-populate new pages with content and property values. Each page can optionally have an icon (emoji, custom emoji by name, or external URL) and a cover image. Set is_skill: true to create a page as a Notion Skill. If a parent is not specified, a private page will be created.Use creation_mode: "draft" when the user wants a durable page but has not named a destination. Draft mode creates a workspace-level private page and cannot be combined with parent. If the user names a private or shared destination, omit creation_mode and create the page under that parent.Example prompts:
  • “Create a project kickoff page under our Projects folder with agenda and team info”
  • “Make a new employee onboarding checklist in our HR database”
  • “Create a new bug report in the tracking database using the ‘Urgent Bug’ template”
  • “Add a new product feature request to our feature database”
  • “Create a page with the 🚀 icon and a cover image”
  • “Draft a private launch plan; we’ll decide where it belongs later”
notion-update-pageUpdate a Notion page’s properties, content, icon, or cover. You can also change whether a page is a Skill or apply database templates to an existing page. Icon, cover, and is_skill can be set alongside any update command.
The update_content command applies content-changing search-and-replace operations as a batch. If any such operation’s old_str doesn’t match content on the page, the call returns a validation error naming the unmatched value and the page is left unchanged. An operation whose old_str and new_str are identical is ignored without checking for a match. Each old_str must be a non-empty string that matches exactly one location, unless replace_all_matches: true is set for that operation.
Example prompts:
  • “Change the status of this task from ‘In Progress’ to ‘Complete’”
  • “Add a new section about risks to the project plan page”
  • “Apply the project kickoff template to this page”
  • “Set the page icon to 🎯 and add a cover image”
  • “Remove the icon from this page”
notion-convert-page-to-skillMarks a Notion page as a Notion Skill without changing its content. Pass the page’s full Notion URL. The page must be in the connected workspace, and you must have permission to edit it.Example prompts:
  • “Convert this page into a skill: https://www.notion.so/example-page-url”
  • “Make our engineering guidelines page available as an AI skill”
notion-move-pagesMove one or more Notion pages or databases to a new parent.Example prompts:
  • “Move my weekly meeting notes page to the ‘Team Meetings’ page”
  • “Reorganize all project documents under the ‘Active Projects’ section”
notion-duplicate-pageDuplicate a Notion page within your workspace. This action completes asynchronously.Example prompts:
  • “Duplicate my project template page so I can use it for the new Q3 initiative”
  • “Make a copy of the meeting agenda template for next week’s planning session”
notion-create-databaseCreates a new Notion database, initial data source, and initial view with the specified properties.Example prompts:
  • “Create a new database to track our customer feedback with fields for customer name, feedback type, priority, and status”
  • “Set up a content calendar database with columns for publish date, content type, and approval status”
notion-create-folderCreate an empty Folder under a parent page.Example prompts:
  • “Create a folder named ‘Project files’ under this page”
  • “Create a folder named ‘Supporting documents’ under this project page”
notion-update-data-sourceUpdate a Notion data source’s properties, name, description, or other attributes.Example prompts:
  • “Add a status field to track project completion”
  • “Update the task database to include priority levels”
notion-create-viewCreate a new view on a Notion database. Supports table, board, list, calendar, timeline, gallery, form, chart, map, and dashboard view types. Use the optional configuration DSL for filters, sorts, grouping, and display options.
Use a page URL or ID for relation filters. Use a user ID or "me" for person, created-by, and last-edited-by filters. Use an option or group name for status filters, and use "verified", "expired", or "none" for verification filters. Page and people names aren’t accepted, so resolve them to a URL or ID first. Read the notion://docs/view-dsl-spec resource for the full syntax.
Example prompts:
  • “Create a board view grouped by Status in my tasks database”
  • “Add a calendar view to the project tracker that shows items by due date”
  • “Set up a filtered table view that only shows in-progress items, sorted by priority”
  • “Create a timeline view for the roadmap database using start and end dates”
  • “Create a chart view showing task counts by status as a bar chart”
  • “Add a form view to the feedback database for collecting responses”
  • “Create a map view of office locations using the Address property”
notion-update-viewUpdate a view’s name, filters, sorts, or display configuration. Only the fields you specify will be changed. Supports clearing existing configuration like filters, sorts, and grouping. Uses the same configuration DSL — and the same filter value formats — as notion-create-view.Example prompts:
  • “Rename the ‘All Tasks’ view to ‘Sprint Board’”
  • “Update the board view to filter by status equals ‘Done’”
  • “Clear the filters on this view and add a sort by created date”
  • “Change the view to group by priority and only show Name and Status columns”
notion-query-data-sourcesQuery Notion data sources with SQL, read rows from one data source, or run a saved view.Pass mode: "rows" and data_source_url to read one data source. Rich-text properties use Notion markdown strings to preserve page and user mentions, link targets, formatting, inline dates, and equations.Rows mode accepts optional filter and sort fields. A filter supports two levels of and or or groups. Sorts run in listed order. limit defaults to 50 and has a maximum of 100.The response contains results and has_more. Each result uses property names as keys. Results include only rows and properties that the connected user can read. Rows mode does not return a cursor.A query can resolve up to 1,000 distinct mention targets. A query over this limit returns an error instead of partial rich text.
SQL output can omit mention text, link targets, and formatting. Their absence in SQL output does not mean that a rich-text property is damaged. Read the property with rows mode or notion-fetch before changing it.
View mode is available on every plan without a tool-specific quota. SQL across one or more data sources is unlimited on Business and Enterprise plans with Notion AI. Other plans share a per-workspace usage limit for single-data-source SQL and receive an upgrade prompt after the allowance is exhausted. Rows mode uses the same allowance as single-data-source SQL.
Example prompts:
  • “What’s due for me this week across all tasks and meeting note action items? Group by priority.”
  • “Show all risks from Engineering and Product databases this month, grouped by owner.”
  • “Read the in-progress rows from the Specs data source. Keep mentions and links in Notes.”
notion-query-meeting-notesQuery the current user’s meeting notes, filtering by meeting-specific properties (such as a title keyword search). Returns meetings where the user is an attendee or creator by default.
Available on all plans, but using it requires a Business plan or higher with Notion AI. On other plans the tool returns an upgrade prompt.
Example prompts:
  • “Find my meeting notes from this week”
  • “What were the action items from my sprint planning meetings?”
  • “Show my 1:1 meeting notes with Alice”
Use notion-list-agents to browse available Custom Agents. Use notion-search-agents to get the Custom Agent URL needed to start a session. Then use these tools to find sessions, start a session, send follow-up messages, wait for a reply, stop a run, and read session events:
  • notion-query-sessions
  • notion-search-sessions
  • notion-spawn-session
  • notion-get-session-status
  • notion-wait-session
  • notion-stop-session
  • notion-send-message-to-session
  • notion-list-session-events
  • notion-read-session-event
Search results include up to 20 matches. Each title is limited to 150 characters, and each matching text span is limited to 300 characters.notion-search-sessions returns no matches and a warning when the workspace’s search index is missing or not ready. Use notion-query-sessions to list sessions while search is unavailable.notion-query-sessions can return an empty page with a cursor. The same is true for notion-search-agents when it is called without a query. Keep following the cursor until the response stops returning one. A notion-search-agents call with a query returns one page without a cursor.
Plan eligibility and tool discovery are separate. When Notion MCP advertises these tools, calling them requires Notion AI access and access to Custom Agents. Without that access, calls return a prompt with a recovery link. When a direct upgrade is available, current_tool_access reports the tools as upgrade_required with an upgrade_url. When Notion routes the user through a plan landing page instead, it reports them as plan_required with a landing_page_url and landing_page_action. If the workspace has a billing restriction, such as an unpaid invoice, calls return a permission error that asks a workspace owner to manage billing, and current_tool_access reports the tools as not_enabled.A connection that lacks the “View threads and interact with agents” capability does not advertise these tools or include them in current_tool_access. Disconnect and reconnect Notion, or enable the capability in the integration’s settings and re-authorize.
Example prompts:
  • “Ask our Support Agent to summarize this customer issue”
  • “Wait for the agent session to finish, then show me its answer”
  • “Search my past agent sessions for the launch decision”
notion-create-commentAdd a comment to a page or specific content. Supports page-level comments, block-level comments (via content selection), and replies to existing discussions.Example prompts:
  • “Add a feedback comment to this design proposal”
  • “Comment on the ‘Budget’ section of the quarterly review”
  • “Reply to the discussion about deadline concerns”
  • “Leave a note on the meeting notes about the action items”
notion-get-commentsLists all comments and discussions on a page. Can include block-level and inline discussions, resolved threads, and full comment content.Example prompts:
  • “Get all discussions on this page, including resolved ones”
  • “Show me the comments on the Requirements section”
  • “Get all feedback comments from last week’s review”
notion-get-teamsRetrieves a list of teams (teamspaces) in the current workspace.Example prompts:
  • “Search for teams by name, and your membership status in each team”
  • “Get a team’s ID to use as a filter for a search”
notion-get-usersLists workspace members and guests with their IDs, names, emails (when available), and types (person or bot). Supports pagination and search by name or email. You can also retrieve a specific user by ID, or the current user (or bot) by passing self.Example prompts:
  • “Get contact details for the user who created this page”
  • “Look up the profile of the person assigned to this task”
  • “Find users whose name or email matches ‘john’”
  • “What’s my Notion user ID and email?”
notion-get-async-taskRetrieves the current status of an async task started by another tool (such as notion-duplicate-page, or notion-create-pages when invoked with allow_async: true). Returns one of queued, running, retrying, succeeded, or failed. When a task has succeeded, the operation’s result is included in the response; when it has failed, an error is included instead.Poll this tool with the task_id from the originating tool’s async_task response. Wait briefly between polls — the original response includes a suggested backoff.Example prompts:
  • “Check whether the page I just duplicated is ready”
  • “Poll this async task until it completes and show me the result”

​
Async page create and update

The notion-create-pages and notion-update-page tools support allow_async: true for long-running page create and update work. When allow_async is omitted or false, the tools keep their normal synchronous result shape. allow_async changes response behavior only; the same validation, permissions, and write operation still apply. Use async mode when asking an assistant to create or update a page with a large amount of markdown content. The initial tool call returns an async_task handle, and the assistant can poll notion-get-async-task with the returned async_task.id passed as task_id until the task reaches succeeded or failed.
If the task is still queued, running, or retrying, wait at least the suggested poll_after_seconds before polling again. A succeeded task includes the operation result. A failed task includes an error object that the assistant can summarize or use to retry with a corrected request.
Tool names may vary for OpenAIWhen connecting with an OpenAI MCP client (e.g. ChatGPT), the notion- prefix is automatically omitted from the notion-fetch and notion-search tools, making them appear as fetch and search, respectively. This is because these specific tool names are required as part of the Deep Research specification for remote MCP servers.

​
Rate limits

Standard API request limits apply per user’s usage of Notion MCP (totaled across all tool calls). Currently, this is an average of 180 requests per minute (3 requests per second). A separate limit applies per workspace, shared across all of its connections and scaled to the workspace’s plan. Because it’s shared, you can be rate limited even when you’re under the per-user limit above. Some MCP tools have additional, tool-specific rate limits that are stricter. These are subject to change over time, but the current values are listed below for reference:
  • Search: 30 requests per minute

​
Examples

To illustrate the above limitations, you’ll experience rate limit errors in your MCP client of choice in any of the following example scenarios (assuming we take the average rate over a large enough time window):
  • 35 searches per minute (exceeds search-specific limit)
  • 12 searches & 170 fetches per minute (exceeds general 180 requests/min limit)
  • 185 fetches per minute (exceeds general 180 requests/min limit)

​
What to do if you’re rate-limited

In most cases, the time it takes to do a complex AI-powered search across Notion and your connected tools means that sequential searches will typically stay under the rate limit. In general, if you encounter rate limit errors, prompt your LLM tool to reduce the amount of parallel searches or operations performed using Notion MCP, and/or try again later.