quickpromptco

Posted on Oct 14 Originally published at quickpromptco.com

Notion MCP for Claude Code: The Official Hosted Server in 1 Command, No API Token

#ai #mcp #productivity #claude

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/mcp

Then 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/mcp

Real run, October 2026. Needs authentication means the server is reachable and waiting for you: run /mcp inside claude to sign in.

Step 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 notion

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

Your Notion pages and databases, readable from the terminal after one OAuth sign-in.

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    https://mcp.notion.com/mcp (HTTP) – Connected

! 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 Notion

If 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 notionApi entry is still registered, Claude sees two sets of Notion tools. Remove it with claude 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-search is 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 notion and 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 mcp commands

Originally published at quickpromptco.com, where the guide is kept up to date.

Top comments (1)

Harun - solo dev • Oct 14

quickpromptco, this is a highly practical and timely guide. the shift from self-hosted api tokens to an oauth-backed hosted mcp server is a massive win for security posture. it enforces least privilege and completely eliminates the risk of leaking ntn_ tokens in .env files or dotfiles.

your warning about prompt injection via notional page content is the most critical takeaway here. when an llm can read arbitrary user-generated content and then execute write tools based on it, that content becomes an active attack vector. keeping execution approval prompts enabled for write tools is an absolute must.

additionally, the --scope project approach for committing .mcp.json is brilliant for team reproducibility. it standardizes the tooling surface across the repo while forcing each developer to authenticate with their own credentials, keeping the permission boundary perfectly clean.

fantastic, no-fluff breakdown of the modern mcp workflow. 🐯🔗