Notion MCP tutorial for Claude Code and Cursor

Notion MCP tutorial: connect Notion to Claude Code or Cursor, authorise access with OAuth, then verify the tools before you let an agent read or edit a real knowledge base. The current low-friction setup uses Notion’s hosted remote MCP server at https://mcp.notion.com/mcp, so you do not need to manage a local API-key flow for the common 2026 workflow.¹

What is Notion MCP, and why use it in 2026?

Notion MCP is a hosted remote MCP server that lets MCP-capable clients talk to Notion through OAuth, instead of a separate manual API-key integration.¹ That matters because it gives you a cleaner setup path in Claude Code and Cursor, while keeping access tied to the pages and databases the signed-in user has actually authorised.²

For professionals and solopreneurs, the practical use case is straightforward: let the model search a knowledge base, draft updates, and make controlled edits without leaving your editor or terminal.²³ The point is not to “AI-enable everything”; it is to connect only the Notion content you already trust, then use that access for retrieval, drafting, and small operational updates.³⁸

How does the access model work?

The key security model is permission inheritance: the AI can only access the Notion pages and databases that the signed-in user has granted, rather than the whole workspace by default.² That is why the safest workflow is to start with a narrow set of pages or databases, confirm the client shows the tools, and only then ask the agent to touch production content.³¹³

How do you set up Notion MCP in Claude Code?

Claude Code setup is usually a two-step flow: register the remote server, then complete browser-based OAuth from the MCP panel.¹²

The current command shown in setup guidance is:

claude mcp add --transport http notion https://mcp.notion.com/mcp

After that, open /mcp in Claude Code and finish the authorisation prompt in the browser.¹² Official connector guidance describes this as a one-click OAuth flow where the client links to Notion and the user approves the workspace connection in the browser.²⁸

Step-by-step Claude Code setup

1. Open a terminal in the environment where you use Claude Code.
2. Register the remote Notion MCP server with the claude mcp add command above.¹²
3. Launch Claude Code and open /mcp.
4. Approve the browser OAuth prompt for the Notion workspace you want to connect.²⁸
5. Confirm the Notion tools appear before sending any read or write prompt.³

What should you test first in Claude Code?

Start with a read-only validation prompt. Ask Claude Code to list the available Notion tools, describe the connected workspace scope, or summarise a known page you explicitly authorised.³¹³ Once that works, test a small controlled edit in a staging page before asking it to update anything user-facing.

How do you set up Notion MCP in Cursor?

Cursor setup usually means adding a global or project MCP server entry in ~/.cursor/mcp.json or .cursor/mcp.json, pointing at https://mcp.notion.com/mcp, then restarting Cursor and approving OAuth on first use.¹²¹²

That difference matters: Claude Code uses the claude mcp add flow and /mcp, while Cursor typically uses mcp.json or its MCP settings UI.¹²¹² If you switch between them, do not assume the configuration is interchangeable.

Cursor setup checklist

• Add the Notion MCP server to the relevant mcp.json file or use Cursor’s MCP settings UI.¹²
• Use https://mcp.notion.com/mcp as the remote endpoint.¹²
• Restart Cursor so the server entry is loaded.¹²
• Approve the OAuth prompt when Cursor first connects to Notion.²⁸
• Confirm the Notion tools are visible before asking for reads or edits.³

Global or project scope: which is better?

Use a project-scoped config when you want a narrow, auditable setup tied to one knowledge base or repo. Use a global config when you need the same Notion connection across multiple projects, but only if you are comfortable with that broader convenience.⁵¹² In either case, the permission boundary still comes from Notion OAuth and the pages you authorise, not from the file location alone.²¹³

What is the safest workflow for reading and writing a Notion knowledge base?

The safest workflow is: connect, authorise, verify, then automate.¹³⁸ That sequence keeps you from granting access too early, and it reduces the chance of an agent editing the wrong database or producing confident but unverified changes.

A sensible operating pattern looks like this:

• Connect the remote server.
• Authorise only the specific Notion pages or databases you need.³¹³
• Verify the tools appear in Claude Code or Cursor.
• Ask for a read-only check first.
• Test a tiny update in a sandbox page.
• Move to production content only after the results are consistent.⁸¹³

Why start read-only?

Read-only prompts let you validate the integration without risking content drift. You can ask the agent to find a page, summarise a knowledge base entry, or check whether a database schema is accessible before it writes anything.³¹³ If the retrieval is wrong, the correction is cheap; if a write goes wrong, the cleanup is not.

What does a controlled write test look like?

Use a single test page or a small database record and ask for one narrow change, such as updating a title, adding a short summary, or appending one approved paragraph.⁸¹³ Then inspect the result manually in Notion before allowing broader updates.

How do Claude Code and Cursor compare for Notion MCP?

Claude Code is better if you want terminal-first control; Cursor is better if you want the connection inside an editor you already use for coding and documentation.¹¹² Both can connect to the same hosted Notion MCP endpoint, but their setup and day-to-day ergonomics are different.

Aspect	Claude Code	Cursor
Setup style	claude mcp add plus /mcp	mcp.json or MCP settings UI
Endpoint	https://mcp.notion.com/mcp	https://mcp.notion.com/mcp
First approval	Browser OAuth in Claude Code flow	OAuth prompt on first use
Best fit	Terminal-based workflows	Editor-based workflows
Main risk to manage	Over-broad prompts after auth	Forgetting which project config is active

Claude Code tends to feel more explicit because the MCP registration is visible in the terminal workflow.¹⁶ Cursor tends to feel more convenient if your notes, code, and content live in the same workspace, but it rewards discipline around project scope and configuration hygiene.¹²

What should you avoid when connecting Notion MCP?

You should avoid assuming that OAuth means full workspace access, and you should avoid sending write prompts before verifying the connected scope.²¹³¹⁵ You should also avoid treating Claude Code and Cursor as if they share the same setup mechanics, because they do not.¹²¹²

Common mistakes to avoid

• Assuming you need a Notion API key first. The hosted Notion MCP flow is built around OAuth to the remote server, not a manual API-key wiring step for the common setup.¹²⁸
• Connecting the whole workspace by default. Access is scoped to the pages and databases the user authorises.²¹³
• Skipping the tool check. Verify the Notion tools appear in the client before asking for reads or edits.³
• Testing production content first. Use a controlled page or database before touching live knowledge base pages.⁸¹³

What does “one-click OAuth” really mean?

It means the client opens a browser-based authorisation flow, and the user approves the workspace connection there.²⁸¹⁵ The phrase is easy to overread; it does not mean “one click, full access,” but rather a simplified consent step with permission-scoped access.

What is the practical workflow for a real knowledge base?

The practical workflow is to use Notion MCP as a controlled bridge between your agent and your documentation system, not as an all-purpose automation layer.³¹³ For a team wiki, content hub, or solopreneur operating manual, that usually means three things: search, summarise, and update with review.

A good first project is a small knowledge base with clear structure:

• A policies page for stable instructions.
• A tasks database for items the agent can update.
• A notes area for draft content the agent can prepare but not publish.

Example prompt sequence

1. “List the Notion pages and databases available in this connection.”
2. “Summarise the page titled ‘Publishing Checklist’.”
3. “Draft an update to the ‘Client FAQ’ page based on these notes.”
4. “Apply this one-line change only to the test page.”
5. “Show me the final diff before any broader update.”

That sequence reflects the official guidance to use scoped access and to test small edits before letting the agent touch production knowledge base content.³¹³ It is slower than hand-waving a full automation, but it is the version that tends to survive real work.

Is Notion MCP only for Claude Code and Cursor?

No. Notion’s hosted MCP endpoint is positioned as compatible with multiple MCP-capable clients that support remote HTTP servers.¹²¹³ Claude Code and Cursor are the most practical examples in current setup guidance, but the underlying pattern is the same: register the remote server, authorise with OAuth, and verify the tools before use.⁵¹²

That compatibility is useful if your stack changes over time. A setup built on the Model Context Protocol is easier to move between clients than a one-off, client-specific integration, which is exactly why the protocol exists.¹⁶ The trade-off is that you still need to understand each client’s registration and approval flow, because those details are not identical.