How to Install Notion MCP with Claude Code: Sync Your Workspace in 5 Minutes (2026)

Notion is where most knowledge work lives in 2026, meeting notes, product specs, customer research, sprint plans, onboarding docs. The Notion MCP server lets Claude Code (and any MCP-compatible agent) read and write across your workspace without you opening a browser tab. Setup takes about five minutes if you have your Notion workspace already structured.

This walkthrough covers the official MCP install, the integration token setup that trips most people up, and a quick test to confirm it works. I'm using Claude Code on macOS for the screenshots and commands, but the steps are nearly identical on Windows and Linux.

What you'll be able to do after this

A few things that worked the first time I ran them:

• Ask Claude "summarize this week's meeting notes" and get a synthesized doc back across multiple Notion pages
• Tell Claude "create a new product spec from this conversation" and watch it spin up a properly formatted Notion page in the right database
• Run "find every page that mentions the Q2 launch" and get back linked excerpts
• Update task statuses in a Notion database based on what got committed in your repo

You don't need to be a developer to do any of this. You do need a Notion workspace where you can create an integration.

Prerequisites

Before the install, confirm three things:

1. Claude Code installed — run claude --version in your terminal. If you see a version number, you're set. If not, install it from the Claude Code docs.

2. A Notion workspace you have admin access to. Personal workspaces work. Free-tier accounts work. You only need permission to create integrations and share pages with them.

3. Node.js 18 or newer for the MCP server. Check with node --version. If you're below 18, upgrade before continuing.

Step 1: Create a Notion integration

This is the step everyone gets wrong, so go slow.

1. Open https://www.notion.so/profile/integrations in a browser. 2. Click New integration. 3. Name it something obvious like "Claude Code MCP". 4. Set the associated workspace to the one you want to connect. 5. Under capabilities, enable: Read content, Update content, Insert content. Leave user information disabled unless you specifically need it, fewer permissions, less risk. 6. Click Save. 7. Copy the internal integration token. It starts with secret_ and is about 50 characters. Save it somewhere safe, you can view it again later, but you'll need it in step 3.

Step 2: Share pages with the integration

A Notion integration can only access pages that have been explicitly shared with it. This is a security feature, not a bug. To grant access:

1. Open the page or database you want Claude to read or write. 2. Click the three-dot menu in the top right. 3. Choose Connections → Connect to → select your integration. 4. The integration now has access to that page and all sub-pages.

For most setups, sharing a single top-level page covers everything below it. If you keep work and personal stuff in the same workspace, only share the work top-level page.

Step 3: Install and configure the MCP server

Open your Claude Code settings file. On macOS and Linux, that's at ~/.claude/settings.json. On Windows, it's at C:\Users\<you>\.claude\settings.json.

Add the Notion MCP server to your mcpServers block:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "secret_YOUR_TOKEN_HERE"
      }
    }
  }
}

Replace secret_YOUR_TOKEN_HERE with the token from step 1. Save the file.

If you already have other MCP servers configured, add the "notion" entry alongside them rather than replacing the block.

Step 4: Restart Claude Code and verify

Quit Claude Code completely and reopen it. The MCP server starts up on launch, there's no separate process to manage.

To verify it's running:

1. Start a new conversation. 2. Type /mcp to see your connected MCP servers. Notion should be in the list with a green status. 3. If it shows red or missing, check the Claude Code logs (Settings → View Logs) for the error message. The most common issues: malformed JSON in settings.json, expired or wrong token, or Node version below 18.

Step 5: Test with a real query

Try a simple read to confirm everything's wired up:

> "What's the title of every page in my workspace that I shared with Claude?"

Claude will use the Notion MCP's search function. You should get back a list of page titles. If you get an empty result and you shared pages in step 2, the integration probably doesn't have search permission, go back and verify the capabilities you enabled.

Now try a write:

> "Create a new page in my workspace called 'Test from Claude' with the body: 'This page was created by Claude via MCP on 2026-05-25'."

Open Notion and confirm the page appeared. If it did, you're done.

What can break

A few failure modes I've hit and seen others hit:

Token starts with ntn_ instead of secret_: You copied a public OAuth token instead of an internal integration token. Generate a new internal integration via the steps above.

MCP starts but every query returns "page not found": The page exists but wasn't shared with the integration. Notion access is per-page; sharing a parent does inherit to children, but a page you created in a different workspace won't show up.

npx fails with permission errors on Windows: Run Claude Code as administrator once, or use the --global install of the MCP server instead of npx.

The MCP server hangs on startup: Usually a firewall or VPN intercepting the npm registry. Try npm config set registry https://registry.npmjs.org/ and confirm npm install -g @notionhq/notion-mcp-server succeeds outside of Claude.

Security notes

The integration token is effectively a password for the pages you've shared. Treat it like one:

• Store it in a password manager, not in a public git repo
• Use a separate integration for each AI tool you connect (Claude, Cursor, etc.) so you can revoke one without breaking others
• Periodically review the integration's access in Notion's settings and revoke shares you no longer need
• For team workspaces, ask the admin to set up a dedicated integration with limited page access rather than using your personal one

The official Notion MCP server is open source, you can read the code at the official repo before installing. Worth a glance if you're in a security-sensitive environment.

Comparison: Notion MCP vs other workspace integrations

If you already installed the Linear MCP, the Notion install will feel familiar. The big difference is Notion's per-page sharing model, which makes setup slightly more involved but more secure than tools that grant blanket workspace access.

What I built with this

The first thing I automated after installing was meeting prep: I have Claude read the page titled "Notes - [Person Name]", summarize the last three entries, and write a one-paragraph context note to Slack before my 1:1s. The script is twelve lines of natural-language Claude commands. It saved me from re-reading old notes every Tuesday morning.

The second was a customer feedback synthesis flow: every Friday, Claude reads the "Customer Feedback" database, pulls all entries tagged "this week", clusters them by theme, and posts the summary in a Notion page tagged "Weekly Synthesis". It replaces a 40-minute manual task with a single prompt.

These aren't impressive demos. They're boring weekly tasks that compound. That's where MCP wins.

FAQ

Q: Does the Notion MCP work with Notion Calendar? Not directly. Notion Calendar uses a separate API. You'd need a Notion Calendar MCP server, which doesn't exist officially yet.

Q: Can I use one integration token across multiple computers? Yes, the token is bound to the integration, not the device. Sharing across team members is technically possible but breaks audit trails. Each person should have their own integration.

Q: Will this work with Notion's free tier? Yes. Integrations don't require a paid Notion plan.

Q: Can Claude create new databases? Yes, but the schema needs to be defined in the request. Claude can't currently auto-design a database from a fuzzy prompt, it'll ask you for the column types.

Q: What if I lose the token? Go back to the integration settings, regenerate it, update settings.json, restart Claude. The old token is revoked the moment you regenerate.

Bottom line

Five minutes of setup buys you the ability to talk to your Notion workspace from your terminal. If you live in Notion already, that's a lot of cognitive overhead removed. The hardest part is remembering to share new pages with the integration as you create them.

Once it's working, try the Linear MCP next. The combination. Notion for context, Linear for execution, covers most of the day-to-day for product teams.

See more skills in our full list of Claude Code productivity skills.