Notion MCP Setup: Connect Claude, Cursor & VS Code (2026)

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 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 notion-ai-search can also 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 is separate from Notion’s hosting and you own the setup and the token, and Notion says the repository is no longer actively maintained or supported.

If you just want Claude to work with your Notion pages, use the hosted server. If you are building something custom or running in a locked-down environment, the self-hosted server is still there, but Notion points everyone to the hosted one. 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.

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 Customize, then Connectors, then click the + button and choose Add custom connector. On a Team or Enterprise plan, an Owner adds it under Organization settings, then Connectors. Paste https://mcp.notion.com/mcp, give it a name like “Notion,” and save. Claude sends you to Notion to sign in and choose the workspace to connect. 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, create a .cursor/mcp.json file in your project with this, or put the same block in ~/.cursor/mcp.json to use it everywhere. Then open Customize in Cursor’s sidebar, enable Notion, and finish the OAuth sign-in.

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

In VS Code, create .vscode/mcp.json in your workspace with this. VS Code uses servers as the top-level key, not mcpServers.

{
  "servers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Then open the Command Palette, run MCP: List Servers, start the Notion server, and finish the OAuth sign-in when prompted.

Every connection ends at the same OAuth consent screen, where you pick the Notion workspace to connect. 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-ai-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 thing to know before you connect

The hosted server does not ask you to pick pages. It acts with your own Notion permissions, and Notion’s docs say a connected client can read and update whatever you can access in the workspace you choose. There is no page-by-page sharing step for the hosted server.

That changes how you think about safety. If you can edit the company wiki, so can an agent you connect. Notion’s own security guidance is to only connect clients you trust, treat content the tools return as untrusted, and turn on confirmation before actions that change content. Do those three things rather than hoping a narrow grant will protect you.

It also changes what “not found” means. If the agent insists it cannot find a page you know exists, the usual cause is that you connected the wrong workspace, or you do not have access to that page yourself. Check the workspace on the consent screen first. Workspace owners can review and revoke connections under Settings, then Connections.

Page-by-page sharing is a different story for the self-hosted server. That one uses an internal integration token, and it only sees pages you have added to that integration. If you have chosen it, that is where “object not found” means “not shared.”

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 can rewrite a page you cared about, because the agent has your permissions. Keep confirmation on, and read what it plans to change before you approve a big edit.

It only sees what you can see: The agent inherits your permissions in the connected workspace. It cannot read a page you cannot open, so a missing answer sometimes means the wrong workspace or missing access, not a missing doc. When results look thin, check which workspace you connected 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 saves any web page with its text and 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. Basic is free, with no account or card, and is capped at 150 bookmarks. Pro at $6 a month, month to month, removes the cap and adds 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

Many 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 shipped a server that writes from the start, 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 launched read-only and is genuinely useful for debugging, though it has since added write tools too. Notion’s write access is a bigger swing, and it pays off, as long as you respect the flip side and keep confirmation on.

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. ContextBolt Basic is free and needs no account, and the endpoint is a $6 a month upgrade when you want your saves in the chat. That is the whole setup. Everything else is detail.