What the Notion MCP Server Actually Gives Claude Code
Connect Claude Code to Notion by adding Notion's own hosted MCP server, at https://mcp.notion.com/mcp, as an MCP server inside Claude Code, then authenticating once in your browser. Once it's connected, Claude Code can search your Notion workspace, read a page or database's real content, and create or update pages, all as part of the same conversation you're already having about a build, not a separate copy-paste step.
This is a server Notion built and runs themselves, not a community workaround stitched together against their public API. That matters for reliability: it's maintained against Notion's actual product, not reverse-engineered from it. If you'd rather run a local server against your own integration token instead of using Notion's hosted one, they also publish an open-source package, @notionhq/notion-mcp-server, for that route. Both are documented in [Notion's own MCP guide](https://developers.notion.com/guides/mcp/get-started-with-mcp).
How to Connect It: Hosted vs Self-Hosted
Most people should use the hosted route, it's fewer steps and Notion manages the server for you.
- In Claude Code, run claude mcp add notion --transport http https://mcp.notion.com/mcp to register the server.
- On first use, Claude Code opens your browser for a Notion OAuth login. Approve it, and the connection is live for that machine going forward.
- In Notion, open the pages or databases you want Claude Code to reach and share them with the connection, the same way you'd share a page with a teammate.
If you'd rather self-host, run the npm package locally instead: npx -y @notionhq/notion-mcp-server, with a NOTION_TOKEN environment variable set to an integration secret you generate at notion.so/my-integrations. The self-hosted route is the same underlying API, it just puts you in charge of the token and the server process instead of Notion.
What This Is Actually Good For
The obvious use is pulling a project brief straight from Notion instead of retyping it into a prompt, see [how to write a project brief for Claude Code](/blog/how-to-write-a-project-brief-for-claude-code) for how that brief should be structured in the first place. Point Claude Code at the linked page and it reads the brief directly rather than you summarizing it by hand.
- Turn a build session into a written changelog or spec pushed back into a client's shared Notion workspace, instead of a summary that only lives in your terminal history.
- Pull a client's existing SOPs or intake docs from Notion as context before scoping a project, so Claude Code isn't guessing at conventions you already wrote down somewhere.
- Keep a running build log in Notion that updates as you work, useful for client visibility if they're used to checking a Notion page rather than a git log.
None of this replaces a real conversation with a client about scope. It removes the manual copy-paste tax between the tool your notes already live in and the tool doing the building.
When Not to Bother With It
Skip the setup for a one-off build with no ongoing Notion presence, or a client who doesn't use Notion at all. It earns its place once there's a real, living set of docs on the other end, a brief, an SOP library, a changelog, something you'd otherwise be retyping every session.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How do I connect Claude Code to Notion?
Add Notion's official hosted MCP server with claude mcp add notion --transport http https://mcp.notion.com/mcp, then authenticate through the browser OAuth flow that opens on first use. Share the specific Notion pages or databases you want reachable with the connection.
Do I need to generate a Notion API token to connect Claude Code?
Not for the hosted route, it authenticates through your browser instead. You only need to generate an integration token from notion.so/my-integrations if you choose the self-hosted @notionhq/notion-mcp-server package instead of Notion's hosted server.
Can Claude Code see my entire Notion workspace once connected?
No. Notion's sharing model is page-level. The MCP connection only sees pages and databases you've explicitly shared with it, the same way sharing works with a teammate, not your full workspace by default.
What's the difference between the hosted and self-hosted Notion MCP server?
The hosted server at mcp.notion.com is run by Notion and authenticates via browser OAuth, no token to manage. The self-hosted @notionhq/notion-mcp-server package runs locally and needs a NOTION_TOKEN integration secret you generate and manage yourself. Both talk to the same underlying Notion API.
Why can't Claude Code see a specific Notion page after I connected it?
The page almost always hasn't been shared with the connection yet. Open the page in Notion, check its Share settings, and confirm the integration or connection is listed there, since an unshared page is invisible to the MCP server by design.
Last reviewed by David Iya on August 26, 2026
