Notion MCP
Connect AI assistants to a Notion workspace over MCP: search, read and write pages, query databases and comments.
Productivity & workspaceGuided#mcp#notion#notes#docs#ai-agents#oauth
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Notion MCP is Notion's hosted Model Context Protocol server at https://mcp.notion.com/mcp. It lets an AI assistant search your workspace, read pages and databases, draft and edit pages, query databases, comment, and (on paid plans) search connected apps such as Slack and Google Drive. Tools work as the signed-in user, so the assistant sees only what you can see in the chosen workspace.
Sign-in (OAuth only)
Notion MCP uses OAuth with your Notion account; there is no API key to paste. Checked live on 2026-11-18:
- A call without a token returns 401 with
WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://mcp.notion.com/.well-known/oauth-protected-resource/mcp", scope="default". - The protected-resource document (resource name "Notion MCP (Beta)") points at
https://mcp.notion.comas the authorization server. - The authorization server metadata lists
/authorize,/token, a dynamic client/registerendpoint, PKCE S256, theauthorization_codeandrefresh_tokengrants and public clients (none) among other auth methods. - Your client opens Notion's consent page, you pick the workspace and approve, and the client stores the token.
In this app: open any MCP request and use the MCP editor's OAuth sign-in; the token lands in the secret accessToken variable (collection auth is Bearer {{accessToken}}). Workspace admins can review and restrict MCP clients (admin controls).
Add it to your AI client
- Claude (web/Desktop): add Notion from the connectors directory and authorise the workspace.
- Claude Code:
claude mcp add --transport http notion https://mcp.notion.com/mcp, then/mcpto sign in. - Cursor (
.cursor/mcp.jsonor~/.cursor/mcp.json):{"mcpServers": {"notion": {"url": "https://mcp.notion.com/mcp"}}}, then enable it and complete OAuth. - VS Code (
.vscode/mcp.json):{"servers": {"notion": {"type": "http", "url": "https://mcp.notion.com/mcp"}}}. - Codex/ChatGPT:
[mcp_servers.notion] url = "https://mcp.notion.com/mcp"thencodex mcp login notion. OpenAI clients seesearchandfetchwithout thenotion-prefix.
Run order and variables
Sign in, then run folder 2 (raw tools/list), folder 3 (who am I, plan limits), folder 4 (search and read; copy a page id into pageId), folder 5 (database rows: copy a collection:// data source URL from a fetched database into dataSourceUrl) and folder 6 (writes: creates a page under pageId, polls the async task, edits the new page and reads comments). Tool names below are the documented ones; some tools and filters need a Business or Enterprise plan with Notion AI, and notion-get-tool-access tells you what your plan allows.
| Area | Tools (selection) |
|---|---|
| Search and read | notion-search, notion-fetch, notion-list-recent-pages, notion-list-page-backlinks, notion-query-meeting-notes, notion-connector-search |
| Workspace | notion-get-self, notion-get-users, notion-get-teams, notion-get-tool-access |
| Pages | notion-create-pages, notion-update-page, notion-move-pages, notion-duplicate-page, notion-delete-pages, notion-get-async-task |
| Databases | notion-create-database, notion-query-data-sources, notion-create-view, notion-update-data-source |
| Comments | notion-create-comment, notion-get-comments |
Safety
Write tools change shared documents: notion-update-page with replace_content overwrites a whole page, notion-move-pages can change who has access (moved pages inherit the new parent's permissions), and notion-delete-pages moves pages to Trash only when user_confirmed: true is set. Try writes in a private scratch page first, keep tool approval on in your client, and remember that page text written by others can contain instructions an assistant should not follow. Rate limits: Notion MCP rate limits.
Common errors
| Response | Meaning | Fix |
|---|---|---|
| HTTP 401 | Missing or expired OAuth token | Sign in again |
validation_error with page_not_found | Page missing or not shared with you | Check the id and your access |
validation_error on create/update | Markdown too large or bad property key | Split content; use keys from the result |
upgrade_required / plan_required | Feature needs a higher plan | See notion-get-tool-access |
| Rate limit error | Too many parallel calls | Slow down and retry |
Docs: Notion MCP overview, connect, supported tools.
Endpoints 17
1. Start here: OAuth discovery
- POSTCall /mcp without a token (expect 401)
{{mcpUrl}}Sends an MCP initialize request with no token. Notion answers 401 with a WWW-Authenticate header naming the protected-resource metadata and the scope default,… - GETProtected resource metadata
{{authBase}}/.well-known/oauth-protected-resource/mcpReads the protected-resource document for the /mcp endpoint: Notion's own authorization server, header-only bearer tokens, the default scope and the resource… - GETAuthorization server metadata
{{authBase}}/.well-known/oauth-authorization-serverReads Notion's OAuth server metadata: authorize, token and dynamic registration endpoints, PKCE S256, supported grants and client authentication methods. MCP…
2. Wire protocol
- POSTList tools (raw JSON-RPC)
{{mcpUrl}}Calls tools/list with your OAuth token and returns every tool your plan and connection expose, each with its JSON input schema. Run Initialize first in the…
3. Workspace and access
- MCPWho am I (workspace and user)
{{mcpUrl}}Calls notion-get-self with an empty object. Returns the connected workspace id and name and the user (type person or bot, id, name and email for people). Run… - MCPCheck tool access for this plan
{{mcpUrl}}Calls notion-get-tool-access with an optional tool_names list (base names such as search and connector_search) and returns each tool's status on your plan… - MCPList teamspaces
{{mcpUrl}}Calls notion-get-teams to list the teamspaces in the current workspace with their ids. A teamspace id can be used as the parent when creating top-level pages… - MCPList workspace users
{{mcpUrl}}Calls notion-get-users to list members and guests with ids, names, emails when available and type (person or bot). It supports search by name or email and…
4. Search and read
- MCPSearch Notion
{{mcpUrl}}Calls notion-search with a short keyword query. It searches pages and databases (not connected apps) and returns titles, urls, ids and highlights; optional… - MCPFetch a page or database
{{mcpUrl}}Calls notion-fetch with id set to a page, database, data source or view id or URL. Pages come back as Notion-flavoured Markdown with path, last edited time,… - MCPRecently viewed pages
{{mcpUrl}}Calls notion-list-recent-pages with limit (1 to 200, default 50). Returns pages and databases you recently viewed, ranked by recency and visits, each with… - MCPPages that link to a page
{{mcpUrl}}Calls notion-list-page-backlinks with page_id (id or URL) and returns pages that link to or mention it, with the kind of link (page_mention, link_to_page,…
5. Databases
- MCPRead rows from a data source
{{mcpUrl}}Calls notion-query-data-sources in rows mode with data_source_url (the collection:// URL from a fetched database). Optional filter and sort narrow the rows;…
6. Writes (use a scratch page)
- MCPCreate a page
{{mcpUrl}}Calls notion-create-pages with parent.page_id (your scratch page), allow_async true and a pages array; each page has properties.title and Markdown content.… - MCPCheck an async task
{{mcpUrl}}Calls notion-get-async-task with task_id from the create or update call. Status is queued, running, retrying, succeeded or failed; on success the operation's… - MCPReplace a page's content
{{mcpUrl}}Calls notion-update-page with page_id, command replace_content and new_str (Markdown). This overwrites the whole page body, so only run it on the page you… - MCPRead comments on a page
{{mcpUrl}}Calls notion-get-comments for a page and lists its discussions and comments, including block-level and resolved threads; your own comments are marked by-you…
API details
- Base URL
https://mcp.notion.com/mcp- Authentication
- OAuth 2.0 (authorization code flow) with 1 scope
- Operations
- 17 operations on 17 pathsPOST 15GET 2
- Main resources
- 1. Start here: OAuth discovery 32. Wire protocol 13. Workspace and access 44. Search and read 45. Databases 16. Writes (use a scratch page) 4
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-18 - Links
- Documentation
How to test the Notion MCP in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Notion MCP collection, without the publisher's secrets.
- Add your credentialsThis API uses OAuth 2.0 (authorization code flow) with 1 scope. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Call /mcp without a token (expect 401)” (POST {{mcpUrl}}), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Notion MCP?
Connect AI assistants to a Notion workspace over MCP: search, read and write pages, query databases and comments. It is listed under Productivity & workspace and has 17 endpoints.
Who publishes the Notion MCP?
It is listed from Notion's public API description (an OpenAPI document), not published by Notion on Swastik Codes. Anyone who controls notion.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Notion MCP?
Requests go to https://mcp.notion.com/mcp. Endpoint paths are added to this base URL.
How do I authenticate with the Notion MCP?
With OAuth 2.0 (authorization code flow) with 1 scope.
How many endpoints does the Notion MCP have?
17 operations on 17 paths (15 POST, 2 GET). The largest groups are 1. Start here: OAuth discovery, 2. Wire protocol, 3. Workspace and access, 4. Search and read.
Is forking the Notion MCP free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.