You ask Claude to write a project update. It writes a good one. Then you copy it, open Notion, find the right page, paste it in, and fix the formatting. Ten minutes later a teammate asks a question that is answered in another Notion doc, so you tab over, search, copy the relevant bit, tab back, and paste it into the chat. Your day is full of these tiny round trips between the AI and the place your work actually lives.
Notion MCP removes the courier job. Instead of you shuttling text between Claude and Notion, the AI reads and writes Notion directly. You say “pull the launch checklist and mark the QA items done” and it finds the page, reads it, and updates it. No copy, no paste, no tab dance.
Notion shipped its official MCP server, hosted at mcp.notion.com/mcp. It works with Claude, Cursor, and VS Code, and unlike a lot of the first-wave servers, it can write, not just read. This guide covers what it does, the exact setup for each client, the use cases that earn their keep, and the one setup step that trips up half the people who try it.
- What it is: Notion’s official MCP server at mcp.notion.com/mcp. It lets Claude, Cursor, and VS Code search, read, create, and edit your Notion pages in plain language.
- Setup: one command for Claude Code (
claude mcp add —transport http notion https://mcp.notion.com/mcp), or add the URL as a custom connector, then sign in with OAuth. - It can write. Unlike read-only servers, Notion MCP creates and edits pages, scoped to the access you grant. That is the whole unlock.
- Best for: turning research into Notion docs, updating trackers by voice, and searching your whole workspace mid-chat.
- Pair it with a bookmarks MCP. Notion holds what you wrote down. The threads and posts you saved on X and Reddit live elsewhere. ContextBolt brings both into one prompt.
What Notion MCP actually does
The Model Context Protocol is an open standard Anthropic released in late 2024. It defines how an AI client talks to an external tool. A server exposes a set of tools, the client calls them mid-conversation, and the results flow straight back into the model’s reasoning. No copy-paste, no export, no leaving the chat.
For Notion, that means the AI can search across your workspace, read a page’s full content, create new pages with real formatting, and edit existing ones. Your notes, docs, wikis, and databases become something the assistant works inside, not a separate app you tab over to.
Notion runs the official server at mcp.notion.com/mcp. Notion built it to convert page content into a “Notion-flavored” Markdown instead of raw block JSON, which is far more token-efficient for an AI to read and write. Notion explains the design in its inside look at the hosted server, and the full setup reference lives in the Notion MCP docs.
The core tools are worth knowing by name. notion-search searches your workspace, and it can reach connected sources like Slack, Google Drive, and Jira in one call. notion-fetch reads a page as Markdown. notion-create-pages builds new pages with properties and content. And the Markdown edit tools update a page’s body in place. The supported tools reference lists the current set. In practice you never memorize it. You ask, and the agent picks the right tool.
Notion MCP means two different things
Here is the confusion nobody clears up first, and it wastes an hour for half the people who search “notion mcp.”
There are two separate things with almost the same name.
The hosted server. Notion runs it at mcp.notion.com/mcp. You connect over OAuth, approve access in your browser, and you are done. Nothing to install, no token to manage, and it stays updated because Notion maintains it. This is what almost everyone wants.
The open-source server. Notion also publishes @notionhq/notion-mcp-server on GitHub and npm. You run it yourself, and you authenticate it with an internal integration token you paste into a config file. It gives you more control and it works fully offline of Notion’s hosting, but you own the setup and the token.
If you just want Claude to work with your Notion pages, use the hosted server. If you are building something custom, running in a locked-down environment, or you need behavior the hosted one does not expose, the self-hosted server is there. The rest of this guide uses the hosted server, because that is the right default for almost everyone.
How to connect Notion MCP to your AI client
The connection is the same underneath for every client. It is the hosted server at mcp.notion.com/mcp, authenticated with OAuth, so no token ever lands in a config file. What changes is the front door.
| Client | How to add | Auth |
|---|---|---|
| Claude Code | claude mcp add —transport http notion https://mcp.notion.com/mcp | OAuth via /mcp |
| Claude Desktop / Claude.ai | Add custom connector, paste the URL | OAuth consent screen |
| Cursor | Settings, MCP, add global server with the URL | ”Needs login” prompt, OAuth |
| VS Code (Copilot) | Add to .vscode/mcp.json, then start it | OAuth |
The fast path for Claude Code. Open a terminal and run claude mcp add --transport http notion https://mcp.notion.com/mcp. Start Claude Code with claude, type /mcp, and finish the OAuth sign-in in the browser window it opens. That is the whole setup. Ask “search my Notion for the roadmap” to confirm the tools loaded.
The fast path for Claude Desktop. Go to Settings, then Connectors, then Add custom connector. Paste https://mcp.notion.com/mcp, give it a name like “Notion,” and save. Claude sends you to Notion to sign in and approve which pages it can touch. Then fully quit and reopen Claude Desktop. A window reload does not pick up a new connector, and that single step is behind most “my server is not working” complaints.
Cursor and VS Code. In Cursor, open Settings, go to MCP, add a new global server with the same URL, then click the “Needs login” prompt to authorize. In VS Code, add the server to .vscode/mcp.json and start it from the command palette. Same URL, same OAuth, tools appear once you approve.
Every connection ends at the same OAuth consent screen, where you choose which parts of your workspace the agent can read and write. That screen is the security model doing its job, so read it rather than clicking straight through.
What you can actually do with it once connected
A connected workspace feels ordinary for five minutes and obvious after a week. Here is the short list of what people actually reach for.
Turn a chat into a Notion doc. You research something with Claude, land on a good answer, and say “write this up as a new page in my Engineering wiki.” It creates the page, formatted, in the right place. The write-up you were going to copy-paste happens in one sentence.
Update a tracker without opening it. “Mark the QA tasks in the launch checklist as done and add a row for the staging bug.” The agent finds the database, edits the rows, and adds the new one. The busywork of keeping a tracker current stops being your job.
Search everything at once. notion-search can reach connected Slack, Drive, and Jira, so “find everything we have on the pricing change” pulls the Notion doc, the Slack thread, and the Jira ticket in a single answer instead of three separate hunts.
Draft from your own context. “Read last week’s standup notes and draft this week’s update in the same format.” The agent reads the real page, matches your structure, and writes the draft. It is grounded in your actual docs, not a generic template.
“Read my product spec page and turn the open questions into a checklist at the bottom.”
That one prompt replaces opening the page, reading it, thinking about the format, and typing the list. That is the shape of the win. Not magic, just the work you were going to do anyway, asked in one line.
The one setup step everyone misses
If the agent connects fine but insists it cannot find a page you know exists, this is almost always why.
Notion MCP can only touch pages you have shared with it. During OAuth you pick which pages and databases the connection can access. Anything outside that grant is invisible to the agent, even though it is right there in your sidebar. So “object not found” usually means “not shared,” not “does not exist.”
The fix is to grant broader access, or to go to the specific page, open the ••• menu, and add the connection there. Give it access to a parent page and every child page inherits it. Most people connect one narrow page during setup, then wonder why the agent is blind to the rest of the workspace. Widen the grant and the problem disappears.
This is also the safety valve. Scoping access to a single project space keeps an agent that can write from editing pages it has no business touching. Grant it what it needs for the task, not the entire company wiki.
Where Notion MCP still needs a human
Honest limits, because a tool you trust blindly is a tool that will eventually burn you.
Write access cuts both ways. The best thing about Notion MCP is that it can edit. The scary thing about Notion MCP is that it can edit. A vague prompt on a broad grant can rewrite a page you cared about. Scope the access, and read what it plans to change before you approve a big edit.
It only sees what you shared. The agent inherits your OAuth grant. It cannot read a page outside that scope, so a missing answer sometimes means the wrong access, not a missing doc. When results look thin, check the grant first.
Huge pages get token-heavy. Asking it to reason over a giant wiki page or a database with thousands of rows will be slow and can hit context limits. Point it at the specific page or filter the query. A narrow ask beats “read my whole workspace” every time.
It answers, it does not watch. MCP is request-and-response. It does not sit in the background and ping you when a doc changes or a task goes overdue. That is what Notion’s own reminders and automations are for. The MCP server is the fast lane for doing, not a monitor. For more on picking servers that earn their slot, see the best MCP servers for knowledge workers.
Why your saved research belongs next to your workspace
Here is the gap nobody setting up Notion MCP talks about. Your workspace is only half of what you know.
Notion holds what you wrote down. It does not hold what you found and never got around to filing. The X thread with the exact framework you wanted to steal for the strategy doc. The Reddit post with the pricing teardown. The LinkedIn post from an operator you follow. That context shapes what you would write in Notion, and none of it is in Notion. It is trapped in a saved tab across three different platforms.
So Notion MCP gives Claude everything you have already documented, and misses everything you meant to. You get an assistant that can edit the strategy doc but has never seen the thread that would make it better.
This is where a bookmarks MCP earns its slot next to the Notion one. ContextBolt is a Chrome extension that captures what you save on X, Reddit, and LinkedIn, tags each save by topic automatically, and exposes the whole collection through a personal MCP endpoint. The free Basic tier covers 150 bookmarks. Pro at $6 a month adds unlimited saves, encrypted cloud sync, and the MCP endpoint any client can call.
Wire it in the same way you wired Notion. Add the custom connector, paste your endpoint, restart. Now Claude reads both halves in one prompt. “Draft the positioning page in Notion and pull anything I saved about competitor messaging” returns the workspace doc and the three threads you bookmarked about that exact topic. Notion tells the agent what you decided. Your bookmarks tell it what you were reading when you decided it. For the walk-through inside Claude Desktop, see the Claude Desktop integration guide, and for the bigger picture of feeding an agent your own context, the personal AI context stack.
The one opinion worth holding
Most of the first wave of official MCP servers shipped read-only, and for good reason. Reading is safe. Writing is where an agent can do real damage. Notion went the other way and shipped a server that writes, and that choice is what makes it more than a fancy search box.
A read-only connector answers questions about your workspace. A read-write one does the work in it. That is a different product. It moves Notion from a place you tab over to when the AI is done thinking, to a place the AI actually builds while it thinks. The Vercel MCP server stayed read-only and is genuinely useful for debugging. Notion’s write access is a bigger swing, and it pays off, as long as you respect the flip side and scope what it can touch.
The other thing worth saying plainly. The MCP server you connect matters more than the client you connect it to. Claude Code, Claude Desktop, Cursor, and VS Code all read the same Notion server. Wire it up once and it pays off across every tool you use. The same is true for the other half of your context. Connect your workspace, connect your bookmarks, and the assistant finally knows both what you decided and what you were reading when you decided it. That is the whole setup. Everything else is detail.