Last Verified: September 2026 — commands checked against Notion’s official MCP docs and the Claude Code MCP docs
Your specs, meeting notes, and bug tickets live in Notion. Your code lives in Claude Code. So every task starts with the same ritual: open the Notion page, copy the requirements, paste them into the terminal, and hope you didn’t miss the comment thread at the bottom where the scope changed.
Notion MCP is Notion’s official hosted MCP server at mcp.notion.com. Claude Code signs in with your Notion account through OAuth and can then search your workspace, read pages and databases as Markdown, and create or update pages, all limited to what you can already see. There’s no API token, no JSON config, and nothing to run locally.
Heads-up: search results still point to the older self-hosted package (@notionhq/notion-mcp-server). Notion’s own README now says that repo is no longer actively maintained and recommends the hosted server instead. That’s the version this guide sets up, for the same reason our community MCP picks skip abandoned servers.
Quick Start
One command adds it for every project:
claude mcp add --transport http --scope user notion https://mcp.notion.com/mcpThen sign in: run /mcp inside Claude Code, select notion, and approve access in the browser window that opens. Total time: about 2 minutes.
⚡ Copy This Prompt: Let Claude Code Install and Verify It For You
Skip the manual steps below and hand the whole job to the agent instead:
You have shell access and the `claude mcp` CLI on this machine. Connect Notion's official hosted MCP server to Claude Code and report back. Do not tell me it's done unless step 5 actually confirms it:
1. Run `claude mcp list`. If a notion entry already exists, show me its command or URL. If it runs `npx @notionhq/notion-mcp-server` (the old self-hosted server), tell me and ask before replacing it.
2. If there's no hosted entry, add it for all projects:
`claude mcp add --transport http --scope user notion https://mcp.notion.com/mcp`
3. Tell me to run `/mcp` inside Claude Code (or `claude mcp login notion` in a terminal) and complete the Notion sign-in in my browser. Wait for me to confirm. Never ask me for a Notion token or integration secret; this server uses OAuth only.
4. Run `claude mcp list` and confirm notion shows Connected.
5. Search my Notion workspace for any page (use a short keyword like "meeting") and show me the titles of up to 3 results. Read only; do not create or edit any page.
If any step fails, give me the exact error and the command that produced it. Do not skip ahead.The agent can’t click “Allow” in Notion’s sign-in page for you, so the prompt pauses there. It also checks for the old self-hosted server so you don’t end up with two Notion entries.
What You’ll Need
| Requirement | Why You Need It | Time |
|---|---|---|
| A Notion account | Any plan works. Some search filters and AI search across connected apps need Business or Enterprise | 0 min |
| Claude Code installed | The client that connects to the hosted server | 0 min |
| A browser on the same machine | The OAuth sign-in opens a Notion approval page | 1 min |
Step-by-Step Setup
Prefer to do it by hand instead of delegating to the agent? Here’s the manual version.
Step 1 — Add the hosted server
~30 sec
--scope user makes Notion available in every project. Use --scope project instead to share it with your team through a .mcp.json file in the repo:
claude mcp add --transport http --scope user notion https://mcp.notion.com/mcpStep 2 — Sign in with OAuth
~1 min
Inside Claude Code, run /mcp, pick notion, and follow the browser prompt. Prefer the terminal? This runs the same sign-in without opening a session:
claude mcp login notionChoose the workspace you want Claude to reach. You can connect only one workspace per entry.
Step 3 — Check how much context it uses
~30 sec
Every MCP server adds tool definitions to Claude’s context. Run /context in Claude Code to see how many tokens Notion takes, and compare it with your other servers.
What Each Piece Does
| Tool | What Claude Can Do With It |
|---|---|
notion-search / notion-ai-search | Find pages by keyword. AI search also looks through connected apps like Slack and Google Drive when your plan includes Notion AI |
notion-fetch | Read a page, database, or data source by URL or ID, including its schema and templates |
notion-create-pages / notion-update-page | Write new pages or change existing ones, such as filling a status property or appending notes |
notion-query-data-sources | Query database rows, for example all tickets marked “Ready for dev” |
notion-create-comment / notion-get-comments | Read and add page comments, including the discussion threads that often hold the real decisions |
| OAuth permissions | Claude sees exactly what your Notion account can see. Workspace owners can review and revoke connections in Settings → Connections |
Verify It’s Actually Working
claude mcp list! notion Needs authentication → run
/mcp and finish the sign-in✘ notionApi npx @notionhq/notion-mcp-server → old self-hosted entry; remove it
Then give Claude a real task:
Find the Notion page for our next feature, list the requirements that don't have a matching file in this repo yet, and don't edit anything in NotionIf Claude calls notion-search, then notion-fetch, and compares the page against your code, the connection and your permissions are working.
Common Mistakes to Avoid
- Following an old tutorial. Guides that tell you to create an internal integration, copy an
ntn_token, and share each page with it are for the self-hosted server. The hosted server needs none of that. - Keeping both servers. If an old
notionApientry is still registered, Claude sees two sets of Notion tools. Remove it withclaude mcp remove notionApi. - Letting Claude edit pages unreviewed. Notion’s security guide warns that page content can carry prompt-injection text. Keep Claude Code’s permission prompts on for Notion write tools and read what it plans to change.
- Hammering search.
notion-searchis limited to 30 requests per minute. If you hit rate-limit errors, ask Claude to run fewer searches in parallel. - Signing in to the wrong workspace. The OAuth page lets you pick a workspace. If search returns nothing, run
claude mcp logout notionand sign in again with the right one.
Q&A
Is it free?
The server is free to connect on any Notion plan. Some features, like AI search across connected apps and certain search filters, depend on your Notion plan.
Can Claude see my whole workspace?
It can see what your Notion account can see, nothing more. For tighter scope, sign in with an account that only has access to the teamspaces Claude needs.
Do I still need the npm package?
No. The hosted server replaces it. Notion says the self-hosted repo may be sunset and that issues there aren’t actively monitored.
Can my team share the setup?
Yes. Add it with --scope project and commit the generated .mcp.json. Each person still signs in with their own Notion account.
How do I remove it?
claude mcp remove notion --scope user. To also revoke the grant on Notion’s side, remove the connection in Notion under Settings → Connections.
Official Resources
- Connect Notion MCP — official setup for Claude Code and other clients
- Notion MCP supported tools — every tool, plan limits, and rate limits
- Notion MCP security best practices — prompt injection and admin controls
- Claude Code MCP docs — scopes, OAuth, and
claude mcpcommands
If this guide ended your copy-paste loop between Notion and the terminal, follow us on X for more setup guides and prompt tips.
Leave a Reply