How to set up the Notion MCP server in Claude Code, Cursor, VS Code and Codex
Checked against the official docs:
Notion MCP lets an AI assistant search your Notion workspace, read pages and databases, and create or update content you have access to. Notion hosts the server, so there is nothing to install: you add one URL and sign in with Notion. This guide covers each major client, the official Claude Code plugin, the endpoint change coming in 2027, sign-in without a browser, and what to check when it fails. It's based on Notion's developer docs for MCP and the official Claude Code plugin (checked 18 November 2026).
Get new guides by email
New MCP servers and agent tools, checked by hand. Free, unsubscribe anytime.
Quick answer
- Server URL:
https://mcp.notion.com/mcp(Streamable HTTP). You sign in with Notion (OAuth) the first time you connect. No API key. - Claude Code:
claude mcp add --transport http notion https://mcp.notion.com/mcp, then run/mcpin Claude Code and authenticate. - Codex: add
[mcp_servers.notion]with thaturlto~/.codex/config.toml, then runcodex mcp login notion. - Cursor and VS Code: add the URL to
mcp.jsonand complete the sign-in when the editor asks. - Easiest of all: if your assistant has a connector or plugin library (Claude, ChatGPT and others), search it for Notion and connect from there.
Free: MCP Starter Checklist
One page: Inspector smoke-test, Claude Code + Cursor connect steps, and the stdout gotcha. Join the list and download it free.
Before you start
- You need to be a workspace member. Guests can't connect: Notion refuses the authorization.
- Any Notion plan works. Some features depend on the plan: MCP tokens (sign-in without a browser) and some search filters need Business or Enterprise, while connected-source search and unlimited SQL queries on databases need Business or Enterprise with Notion AI. Request limits are also higher on Business and Enterprise.
- The assistant gets your access. A connected client can read and change anything you can access in the workspace you pick, so only connect clients you trust.
For a shorter overview, see the Notion MCP listing.
What Notion MCP can do
Notion's docs list the full tool set. The ones you will use most:
notion-search: find pages and databases by topic or title.notion-fetchopens a page, database or connected-source result.notion-create-pagesandnotion-update-page: draft documents, apply database templates, and update content and properties.notion-create-databaseandnotion-query-data-sources: create databases with properties and views, and read a saved view or find matching entries.notion-create-commentandnotion-get-comments: comment on pages and read discussions.notion-create-file-upload: upload images and other files up to 20 MiB.
In OpenAI clients such as ChatGPT, notion-search and notion-fetch show up as search and fetch.
Claude Code
Add the server from your terminal:
claude mcp add --transport http notion https://mcp.notion.com/mcpThen start Claude Code, run /mcp, pick notion and follow the sign-in flow in your browser. The default scope is local (only you, in this project). Add --scope user to use it in every project, or --scope project to share it with your team through a .mcp.json file in the repo; each teammate still signs in with their own Notion account.
The official Notion plugin
Notion also publishes a Claude Code plugin that bundles the same MCP server with Notion skills (meeting prep, specs to tasks, project setup and more) and slash commands for search, pages, databases and tasks:
claude plugin marketplace add makenotion/claude-code-notion-plugin
claude plugin install notion-workspace-plugin@notion-plugin-marketplaceRestart Claude Code afterwards so the server starts. Use the plugin or the manual claude mcp add entry, not both. More on plugins: how to install Claude Code plugins. If Claude Code keeps saying the server needs authentication, see fix Claude Code MCP "needs authentication".
Claude Desktop, Claude.ai and ChatGPT
Use the built-in connector instead of a config file: open your assistant's connector library, search for Notion, select it and approve access to your workspace. You can also start from Notion: open Settings → Notion MCP, browse the directory, pick your assistant and follow its instructions.
Codex
Add the server to ~/.codex/config.toml:
[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"Then sign in:
codex mcp login notionTo share the setup with your team, put the same block in .codex/config.toml at the root of your project. More on Codex config: how to add an MCP server to Codex.
Cursor
Create .cursor/mcp.json in your project (or use ~/.cursor/mcp.json to make it available in every project):
{
"mcpServers": {
"notion": {
"url": "https://mcp.notion.com/mcp"
}
}
}Then open Customize in Cursor's sidebar, enable Notion and complete the sign-in. Details on file locations: how to add an MCP server to Cursor.
VS Code (GitHub Copilot)
Create .vscode/mcp.json in your workspace:
{
"servers": {
"notion": {
"type": "http",
"url": "https://mcp.notion.com/mcp"
}
}
}Open the Command Palette, run MCP: List Servers, start the Notion server and complete the sign-in. For every workspace, run MCP: Open User Configuration and add the same entry there. VS Code uses servers, not mcpServers; see how to add an MCP server to VS Code.
Other clients
Add Notion as a remote server with the Streamable HTTP transport and the URL https://mcp.notion.com/mcp. For clients that take a JSON config, the standard block works:
{
"mcpServers": {
"notion": {
"url": "https://mcp.notion.com/mcp"
}
}
}Antigravity uses serverUrl instead of url in its mcp_config.json. Notion recommends adding it there as a custom server rather than using the pre-made Notion entry in Antigravity's MCP gallery, which runs the old, deprecated package. If a client can only run local servers, use the mcp-remote bridge:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
}
}
}On Windows, if the client can't start npx, see fixing spawn npx ENOENT.
Moving off the old SSE endpoint
Notion will retire its legacy endpoint, https://mcp.notion.com/sse, on 23 February 2027. If an older setup still uses it, open the client's Notion server settings, change the transport from SSE to Streamable HTTP, replace the URL with https://mcp.notion.com/mcp, save, sign in again if asked and check that the Notion tools appear. If the client only offers SSE, update it to a version that supports Streamable HTTP.
Connecting without a browser sign-in
On Business and Enterprise plans, a workspace owner can create an MCP token with New MCP token in Notion's Developer portal. The client then sends that token as a bearer token (an Authorization: Bearer header) to https://mcp.notion.com/mcp, with no browser sign-in. Treat it like a password and keep it out of files you commit. Enterprise workspaces with SAML SSO can also use enterprise-managed authorization through their identity provider.
Check that it works
Open your client's MCP list and confirm notion is connected. Then try:
Search my Notion workspace for pages about pricing and summarize what they say, with links.The assistant should call notion-search (or search in OpenAI clients). If it answers from memory instead, mention Notion in the prompt.
Use it safely
- Watch for prompt injection. A page, comment or connected-source result could contain instructions aimed at the assistant. Treat what the tools return as untrusted, and review proposed actions before you approve them.
- Keep confirmations on. Turn on your client's confirmation step for actions that change content, so you see each edit before it runs.
- Data can leave Notion. The client may send what it reads to other services. That can include items from connected sources such as Slack threads, Google Drive files and emails, when the assistant opens them from a search result.
- Workspace owners can manage connected clients under Settings → Notion MCP → Manage workspace clients. Limiting which clients members can connect needs the Enterprise plan.
Troubleshooting
- "Guests can't connect": only workspace members can use Notion MCP. Ask a workspace owner to make you a member, or connect a workspace where you are one.
- Sign-in fails or keeps asking again: complete the sign-in flow when prompted, then disconnect and reconnect the client (look for Clear authentication or Disconnect in its MCP settings). Check that you have access to the workspace you picked.
- An enterprise policy blocks the connection: an admin may restrict which MCP servers you can add. Ask whether Notion MCP is allowed in your assistant. Notion workspace owners also have admin controls for MCP.
- Rate limit errors: Notion MCP uses the standard Notion API request limits, and every tool call counts. Ask the assistant to do fewer things in parallel, or try again later. The server retries once by itself only when the wait is 2 seconds or less.
- The client only supports local servers: use the
mcp-remoteconfig above. - Tools stopped working on an old setup: check whether it still points at the
/sseendpoint, and switch it tohttps://mcp.notion.com/mcp.
FAQ
Is Notion MCP free?
Notion MCP works on every Notion plan. MCP tokens, some search filters, connected-source search and unlimited SQL database queries need Business or Enterprise (the last two also need Notion AI), as listed above.
Should I use the hosted server or the open-source notion-mcp-server?
The hosted server at https://mcp.notion.com/mcp. Notion says the open-source notion-mcp-server package is no longer actively maintained; it uses an integration token and you have to run it yourself. Notion lists it only as a last resort.
Can I share the setup with my team?
Yes. Commit the server entry (a project .mcp.json for Claude Code, .codex/config.toml for Codex, .cursor/mcp.json for Cursor or .vscode/mcp.json for VS Code). The file holds no secret, and each person signs in with their own Notion account.
What other MCP servers work well alongside Notion?
For tasks and issues, see the Linear MCP server. For a wider list, see the best MCP servers for Claude Code.
Sources
Commands and config above come from these official docs. Tools change often, so check them for the latest steps.
- Notion docs: Connect to Notion MCP
- Notion docs: Notion MCP overview
- Notion docs: Notion MCP tool FAQs (full tool list)
- Notion docs: Notion MCP rate limits
- Notion docs: Security best practices
- makenotion/claude-code-notion-plugin on GitHub
- Claude Code docs: Connect Claude Code to tools via MCP
PluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email pluginstackai@gmail.com.
Related guides
Tools in this guide
Get new guides by email
New MCP servers and agent tools, checked by hand. Free, unsubscribe anytime.