Notion MCP

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'notionmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Notion MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'notionmcp_notion-create-attachment',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "notionmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Notion MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="notionmcp_notion-create-attachment",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Notion-update-folder records — Update an existing Notion Folder: add uploaded files, remove files by their exact fetched URLs, or add a new nested subfolder
• Notion-search-agents records — Search agents by name or description, or browse the current user’s favorite agents and the workspace’s newest agents
• Notion-list-shared-pages records — List pages and databases in the current user’s Shared sidebar section
• Notion-list-recent-pages records — List pages and databases the current user recently viewed, ranked by recency and visit frequency
• Notion-list-private-pages records — List the current user’s top-level pages and databases in their Private sidebar section
• Notion-list-favorite-pages records — List the current user’s favorite pages and databases in sidebar order

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

notionmcp_notion-convert-page-to-skill#Mark a Notion page as an AI skill. The page must be in the current workspace, and the authenticated user must have permission to edit it.1 param▾

Mark a Notion page as an AI skill. The page must be in the current workspace, and the authenticated user must have permission to edit it.

NameTypeRequiredDescription

page_urlstringrequiredThe full Notion URL of the page to mark as an AI skill. Example: https://www.notion.so/workspace/My-Page-1234567890abcdef1234567890abcdef

notionmcp_notion-create-attachment#Create an attachment and upload it to Notion. Provide exactly one of content (small UTF-8 text), source_url (a direct publicly reachable HTTPS URL), or source_file_id (a file already uploaded by this integration).5 params▾

Create an attachment and upload it to Notion. Provide exactly one of content (small UTF-8 text), source_url (a direct publicly reachable HTTPS URL), or source_file_id (a file already uploaded by this integration).

NameTypeRequiredDescription

contentstringoptionalThe complete UTF-8 text content of the file. Maximum 200 KiB after UTF-8 encoding. Requires filename. Example: "Hello world".

content_typestringoptionalOptional MIME type, such as text/html or application/pdf. It must match the filename extension; omit it to infer the type from the filename. Omit it with source_file_id.

filenamestringoptionalThe filename to create in Notion, including a supported extension such as .html, .md, .pdf, or .png. Required with content and source_url. Omit it with source_file_id.

source_file_idstringoptionalThe ID of a file upload this exact integration already created, using create-file-upload or the Notion File Upload API with this integration's token. Its status must be uploaded. Example: "12345678-90ab-cdef-1234-567890abcdef".

source_urlstringoptionalA direct, publicly reachable HTTPS URL from which Notion can download the file within one minute. Redirects, private network addresses, custom request headers, and cookies are not supported. Requires filename.

notionmcp_notion-create-comment#Add a comment to a Notion page or inline discussion thread.5 params▾

Add a comment to a Notion page or inline discussion thread.

NameTypeRequiredDescription

page_idstringrequiredThe ID of the page to comment on (with or without dashes).

discussion_idstringoptionalThe ID or URL of an existing discussion to reply to (e.g., discussion://pageId/blockId/discussionId).

markdownstringoptionalThe content of the comment as a Markdown string. Provide exactly one of markdown or rich_text. For exact syntax, read the MCP resource notion://docs/enhanced-markdown-spec through your MCP client's resource-reading interface. Do not pass this URI to the Notion fetch tool or any URL-fetching tool, and use only the Rich text types and Mentions syntax that comments support. Comments support inline formatting (bold, italic, strikethrough, underline, code, links), inline math using $`Equation`$, and user/page/database/date mention tags such as <mention-date start="YYYY-MM-DD"/>. Do not use UI shortcuts like @today, @name, [[page]], or autocomplete-style emoji syntax; those are editor affordances, not markdown syntax. Mention tags must include a real url where required by the spec. Block-level Markdown such as fenced code blocks, headings, lists, tables, and blockquotes is stored as plain comment text rather than rendered as blocks.

rich_textarrayoptionalAn array of rich text objects that represent the content of the comment. Provide exactly one of rich_text or markdown.

selection_with_ellipsisstringoptionalUnique start and end snippet of the content to comment on. DO NOT provide the entire string. Instead, provide up to the first ~10 characters, an ellipsis, and then up to the last ~10 characters. Make sure you provide enough of the start and end snippet to uniquely identify the content. For example: "# Section heading...last paragraph."

notionmcp_notion-create-database#Create a new Notion database using a SQL DDL schema definition.5 params▾

Create a new Notion database using a SQL DDL schema definition.

NameTypeRequiredDescription

database_typestringoptionalCreate a typed database with Notion's canonical required properties and metadata instead of a custom SQL schema. Supported values: tasks, projects, skills. Cannot be combined with schema. Example: "tasks".

descriptionstringoptionalThe description of the new database.

parentobjectoptionalThe parent under which to create the new database. If omitted, the database will be created as a private page at the workspace level.

schemastringoptionalSQL DDL CREATE TABLE statement defining the database schema. Column names must be double-quoted, type options use single quotes. Cannot be combined with database_type.

titlestringoptionalThe title of the new database.

notionmcp_notion-create-file-upload#Create a short-lived URL for uploading one local file directly to Notion. After calling this, send a multipart/form-data POST to the returned upload_url with the file and headers.2 params▾

Create a short-lived URL for uploading one local file directly to Notion. After calling this, send a multipart/form-data POST to the returned upload_url with the file and headers.

NameTypeRequiredDescription

filenamestringrequiredThe filename to create in Notion, including a supported extension such as .pdf, .png, or .zip. Example: "diagram.png".

content_typestringoptionalOptional MIME type, such as application/pdf or image/png. Prefer omitting it so the type is inferred from the filename.

notionmcp_notion-create-folder#Create an empty Notion Folder under a page or another Folder. This tool creates only the empty Folder; it is non-idempotent and creates a new Folder on every successful call.2 params▾

Create an empty Notion Folder under a page or another Folder. This tool creates only the empty Folder; it is non-idempotent and creates a new Folder on every successful call.

NameTypeRequiredDescription

parentstringrequiredWhere to create the Folder. Provide either a page_id (top-level Folder owned by a page) or a folder_id (nested Folder inside another Folder).

titlestringoptionalThe title of the new Folder. Example: "Design Assets".

notionmcp_notion-create-pages#Create one or more Notion pages with properties and Markdown content.3 params▾

Create one or more Notion pages with properties and Markdown content.

NameTypeRequiredDescription

pagesarrayrequiredThe pages to create.

allow_asyncbooleanoptionalSet to true to opt into receiving an async_task result when this create operation is accepted for background execution instead of completing synchronously. Poll the returned task_id with the get-async-task tool. If omitted or false, the tool keeps the existing synchronous result shape. Example: true.

parentstringoptionalThe 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.

notionmcp_notion-create-view#Create a new view on a Notion database with optional filters and sorts.6 params▾

Create a new view on a Notion database with optional filters and sorts.

NameTypeRequiredDescription

data_source_idstringrequiredThe data source (collection) ID. Accepts a collection:// URI from <data-source> tags or a bare UUID.

namestringrequiredThe name of the view.

typestringrequiredThe view type. Accepted values: table, board, calendar, gallery, list, timeline.

configurestringoptionalView configuration DSL string. Supports FILTER, SORT BY, GROUP BY, CALENDAR BY, TIMELINE BY, MAP BY, CHART, FORM, SHOW, HIDE, COVER, WRAP CELLS, and FREEZE COLUMNS directives. See notion://docs/view-dsl-spec.

database_idstringoptionalThe database to add a view tab to. Accepts a Notion URL or a bare UUID. Mutually exclusive with `parent_page_id`; exactly one must be provided.

parent_page_idstringoptionalA page to create an inline linked database view on. Accepts a Notion URL or a bare UUID. The new linked view block is appended at the end of the page and references `data_source_id`. Mutually exclusive with `database_id`; exactly one must be provided.

notionmcp_notion-download-attachment#Download the contents of a small UTF-8 text attachment created by the Notion create-attachment tool. Limited to 200 KiB and text formats such as HTML, Markdown, plain text, CSV, JSON, XML, CSS, YAML, TSV, calendar, GPX, or SVG.1 param▾

Download the contents of a small UTF-8 text attachment created by the Notion create-attachment tool. Limited to 200 KiB and text formats such as HTML, Markdown, plain text, CSV, JSON, XML, CSS, YAML, TSV, calendar, GPX, or SVG.

NameTypeRequiredDescription

file_upload_idstringrequiredThe FileUpload ID returned by the create-attachment tool. Example: "12345678-90ab-cdef-1234-567890abcdef".

notionmcp_notion-duplicate-page#Duplicate an existing Notion page within the current workspace.1 param▾

Duplicate an existing Notion page within the current workspace.

NameTypeRequiredDescription

page_idstringrequiredThe ID of the page to duplicate. This is a v4 UUID, with or without dashes, and can be parsed from a Notion page URL.

notionmcp_notion-fetch#Retrieve details about a Notion page, database, or data source by URL or ID.3 params▾

Retrieve details about a Notion page, database, or data source by URL or ID.

NameTypeRequiredDescription

idstringrequiredThe ID or URL of the Notion page, database, or data source to fetch. Supports notion.so URLs, Notion Sites URLs (*.notion.site), raw UUIDs, and data source URLs (collection://...).

include_discussionsbooleanoptionalSet to true to include discussion threads in the response.

include_transcriptbooleanoptionalSet to true to include a meeting transcript in the response.

notionmcp_notion-get-async-task#Retrieve the current status of an async task started by another tool (for example, create-pages or update-page called with allow_async: true). Status is one of queued, running, retrying, succeeded, or failed.1 param▾

Retrieve the current status of an async task started by another tool (for example, create-pages or update-page called with allow_async: true). Status is one of queued, running, retrying, succeeded, or failed.

NameTypeRequiredDescription

task_idstringrequiredThe ID of the async task to retrieve, as returned in the async_task response of the tool that started it. Example: "task_abc123".

notionmcp_notion-get-comments#Retrieve comments and discussion threads from a Notion page.4 params▾

Retrieve comments and discussion threads from a Notion page.

NameTypeRequiredDescription

page_idstringrequiredIdentifier for a Notion page.

discussion_idstringoptionalFetch a specific discussion by ID or discussion URL (e.g., discussion://pageId/blockId/discussionId).

include_all_blocksbooleanoptionalSet to true to return all comment blocks, not just the first.

include_resolvedbooleanoptionalSet to true to include resolved discussions in the response.

notionmcp_notion-get-teams#Retrieve a list of teams (teamspaces) in the current workspace.1 param▾

Retrieve a list of teams (teamspaces) in the current workspace.

NameTypeRequiredDescription

querystringoptionalOptional search query to filter teams by name (case-insensitive).

notionmcp_notion-get-users#Retrieve a list of users in the current Notion workspace.4 params▾

Retrieve a list of users in the current Notion workspace.

NameTypeRequiredDescription

page_sizeintegeroptionalNumber of users to return per page (default: 100, max: 100).

querystringoptionalOptional search query to filter users by name or email (case-insensitive).

start_cursorstringoptionalCursor for pagination. Use the next_cursor value from the previous response to get the next page.

user_idstringoptionalReturn only the user matching this ID. Pass "self" to fetch the current user.

notionmcp_notion-list-favorite-pages#List the current user's favorite pages and databases in sidebar order. Use this when the user refers to a favorite or pinned workspace item.2 params▾

List the current user's favorite pages and databases in sidebar order. Use this when the user refers to a favorite or pinned workspace item.

NameTypeRequiredDescription

cursorstringoptionalOpaque pagination cursor from the previous response. Example: "eyJpZCI6IjEwMDI1In0=".

limitnumberoptionalMaximum results to return (1-200). Example: 25.

notionmcp_notion-list-private-pages#List the current user's top-level pages and databases in their Private sidebar section. Use this to browse private workspace structure; use search when looking for content by meaning or keyword.2 params▾

List the current user's top-level pages and databases in their Private sidebar section. Use this to browse private workspace structure; use search when looking for content by meaning or keyword.

NameTypeRequiredDescription

cursorstringoptionalOpaque pagination cursor from the previous response. Example: "eyJpZCI6IjEwMDI1In0=".

limitnumberoptionalMaximum results to return (1-200). Example: 25.

notionmcp_notion-list-recent-pages#List pages and databases the current user recently viewed, ranked by recency and visit frequency. Use this to recover likely navigation context when the user refers to something they were recently working on.2 params▾

List pages and databases the current user recently viewed, ranked by recency and visit frequency. Use this to recover likely navigation context when the user refers to something they were recently working on.

NameTypeRequiredDescription

cursorstringoptionalOpaque pagination cursor from the previous response. Example: "eyJpZCI6IjEwMDI1In0=".

limitnumberoptionalMaximum results to return (1-200). Example: 25.

notionmcp_notion-list-shared-pages#List pages and databases in the current user's Shared sidebar section. Use this to browse content shared directly with the user; use search when looking for content by meaning or keyword.2 params▾

List pages and databases in the current user's Shared sidebar section. Use this to browse content shared directly with the user; use search when looking for content by meaning or keyword.

NameTypeRequiredDescription

cursorstringoptionalOpaque pagination cursor from the previous response. Example: "eyJpZCI6IjEwMDI1In0=".

limitnumberoptionalMaximum results to return (1-200). Example: 25.

notionmcp_notion-move-pages#Move one or more Notion pages or databases to a new parent.2 params▾

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

NameTypeRequiredDescription

new_parentstringrequiredThe 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.

page_or_database_idsarrayrequiredAn 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 <page> or <database> URL given by the "search" or "fetch" tool). Data Sources under Databases can't be moved individually.

notionmcp_notion-query-data-sources#Query Notion databases using SQL or by specifying a view.1 param▾

Query Notion databases using SQL or by specifying a view.

NameTypeRequiredDescription

datastringrequiredThe data required for querying data sources

notionmcp_notion-query-meeting-notes#Query the current user's Notion meeting notes data source with optional filters.1 param▾

Query the current user's Notion meeting notes data source with optional filters.

NameTypeRequiredDescription

filterobjectoptionalAcceptable filter for querying current user's meeting notes data source.

notionmcp_notion-search#Search pages, databases, and connected sources in the Notion workspace.9 params▾

Search pages, databases, and connected sources in the Notion workspace.

NameTypeRequiredDescription

querystringrequiredSemantic 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 "john@example.com"

content_search_modestringoptionalHow to search within page content. Accepted values: keyword, semantic.

data_source_urlstringoptionalOptionally, 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. <data-source> 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.

filtersobjectoptionalOptionally provide filters to apply to the search results. Only valid when query_type is 'internal'.

max_highlight_lengthintegeroptionalMaximum character length for result highlights (default 200). Set to 0 to omit highlights entirely.

page_sizeintegeroptionalMaximum number of results to return (default 10). Lower values reduce response size.

page_urlstringoptionalOptionally, 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.

query_typestringoptionalThe search mode. Accepted values: semantic, keyword.

teamspace_idstringoptionalOptionally, 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.

notionmcp_notion-search-agents#Search agents by name or description, or browse the current user's favorite agents and the workspace's newest agents.4 params▾

Search agents by name or description, or browse the current user's favorite agents and the workspace's newest agents.

NameTypeRequiredDescription

scopestringrequiredWhich agents to list: "favorites" for the current user's favorite agents, or "workspace" for agents shared with the workspace.

cursorstringoptionalOpaque pagination cursor from the previous response. Example: "eyJpZCI6IjEwMDI1In0=".

limitnumberoptionalMaximum results to return (1-200). Example: 25.

querystringoptionalSearch text matched against agent names and descriptions. When omitted, favorites are returned in sidebar order and workspace agents are returned newest first.

notionmcp_notion-update-data-source#Update a Notion data source's schema, title, or attributes using SQL DDL statements.6 params▾

Update a Notion data source's schema, title, or attributes using SQL DDL statements.

NameTypeRequiredDescription

data_source_idstringrequiredThe data source to update. Accepts a collection:// URI from <data-source> tags, a bare UUID, or a database ID (only if the database has a single data source).

descriptionstringoptionalThe new description of the data source.

in_trashbooleanoptionalSet to true to move the data source to the trash.

is_inlinebooleanoptionalSet to true to make the database display inline within a page.

statementsstringoptionalSemicolon-separated SQL DDL statements to update the schema. Supports ADD COLUMN, DROP COLUMN, RENAME COLUMN, ALTER COLUMN SET.

titlestringoptionalThe new title of the data source.

notionmcp_notion-update-folder#Update an existing Notion Folder: add uploaded files, remove files by their exact fetched URLs, or add a new nested subfolder. Use exactly one command shape at a time.5 params▾

Update an existing Notion Folder: add uploaded files, remove files by their exact fetched URLs, or add a new nested subfolder. Use exactly one command shape at a time.

NameTypeRequiredDescription

commandstringrequiredThe Folder update to apply. Accepted values: add_files, remove_files, add_subfolder.

folder_idstringrequiredThe ID of the Folder to update, with or without dashes.

file_upload_idsarrayoptionalRequired for add_files. One or more file upload IDs returned by the file upload tools.

file_urlsarrayoptionalRequired for remove_files. The exact file URLs shown in the Folder's latest fetch output.

titlestringoptionalRequired for add_subfolder. The new Folder's title.

notionmcp_notion-update-page#Update a Notion page's properties, content, icon, cover, or verification status.15 params▾

Update a Notion page's properties, content, icon, cover, or verification status.

NameTypeRequiredDescription

commandstringrequiredThe update operation to perform. Accepted values: update_properties, update_content, replace_content, insert_content, apply_template, update_verification.

page_idstringrequiredThe ID of the page to update, with or without dashes.

allow_asyncbooleanoptionalSet to true to opt into an async_task response after the update is validated, durably persisted, and accepted for queued execution. If omitted or false, the tool waits for a synchronous result when possible, but may still return a pollable async_task response if queued execution exceeds the synchronous wait deadline. Example: true.

allow_deleting_contentbooleanoptionalSet to true to confirm deletion of child pages or databases when replacing content.

contentstringoptionalRequired for "insert_content" command. The markdown content to insert into the page.

content_updatesarrayoptionalRequired for "update_content" command. An array of search-and-replace operations, each with old_str (content to find) and new_str (replacement content).

coverstringoptionalAn external image URL for the page cover. Use "none" to remove the cover. Omit to leave unchanged. Can be set alongside any command.

iconstringoptionalAn emoji character (e.g. "🚀"), a custom emoji by name (e.g. ":rocket_ship:"), or an external image URL. Use "none" to remove the icon. Omit to leave unchanged. Can be set alongside any command.

is_skillbooleanoptionalSet to true to mark this page as an AI skill, or false to remove the AI skill designation. Can be set alongside any command. Example: true.

new_strstringoptionalRequired for "replace_content" command. The new content string to replace the entire page content with.

positionstringoptionalOptional for "insert_content" command. Use {"type":"start"} to prepend content or {"type":"end"} to append content. Omit to append.

propertiesobjectoptionalRequired for "update_properties" command. A JSON object that updates the page's properties. For pages in a database, use the SQLite schema definition shown in <database>. For pages outside of a database, the only allowed property is "title", which is the title of the page in inline markdown format. Use null to remove a property's value.

template_idstringoptionalRequired for "apply_template" command. The ID of a template to apply to this page. Template content is appended to any existing page content.

verification_expiry_daysintegeroptionalOptional for "update_verification" command when verification_status is "verified". Number of days until verification expires (e.g. 7, 30, 90). Omit for indefinite verification.

verification_statusstringoptionalThe verification state to set. Accepted values: verified, unverified.

notionmcp_notion-update-view#Update a Notion database view's name, filters, sorts, or display configuration.3 params▾

Update a Notion database view's name, filters, sorts, or display configuration.

NameTypeRequiredDescription

view_idstringrequiredThe view to update. Accepts a view:// URI, a Notion URL with ?v= parameter, or a bare UUID.

configurestringoptionalView configuration DSL string. Supports FILTER, SORT BY, GROUP BY, CALENDAR BY, TIMELINE BY, MAP BY, CHART, FORM, SHOW, HIDE, COVER, WRAP CELLS, FREEZE COLUMNS, and CLEAR directives.

namestringoptionalNew name for the view.