Claude Code Notion MCP Integration Guide

What Notion MCP Exposes to Claude

Notion serves as the operational brain for many development teams. Project specs, technical documentation, bug databases, roadmaps, and meeting notes all live there. The Notion MCP server gives Claude Code structured access to that knowledge. If you are new to Claude Code, the Claude Code Course is a good foundation before layering in MCP integrations.

Once connected, Claude can read and write across three core Notion primitives:

• Pages: full page content including text, code blocks, headings, and rich text
• Databases: Notion databases with filtering, sorting, and record creation
• Blocks: individual content blocks within pages for targeted reading or editing

This creates a two-way connection between your code and your documentation. Claude can pull context from Notion before writing code. It can write structured output back to Notion after completing a task. Teams that use Notion heavily find this eliminates a significant amount of copy-paste work.

Notion MCP turns your documentation from a reference you consult into context Claude uses automatically.

Setting Up a Notion Integration

Before configuring the MCP server, you need a Notion Integration Token. Notion integrations are scoped to specific pages and databases, giving you control over what Claude can access.

Step 1: Create a Notion integration

Go to notion.so/my-integrations and click “New integration.” Give it a name (for example, “Claude Code”), select your workspace, and choose the capabilities you need. For most workflows, “Read content” and “Update content” are sufficient. “Insert content” is needed for writing new pages or records.

Step 2: Copy the integration token

After creating the integration, copy the Internal Integration Token. It starts with secret_.

Step 3: Share pages with the integration

Notion integrations only have access to pages you explicitly share with them. Open each page or database Claude should access, click the three-dot menu, select “Add connections,” and choose your integration. Pages inherit this permission to their child pages.

Installation and Configuration

Install the Notion MCP server:

npm install -g @notionhq/notion-mcp-server

Add the server to your Claude Code config. Use .mcp.json for project-level access or the global config for cross-project Notion access:

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

Restart Claude Code after saving. Verify the connection:

Can you access my Notion workspace? List a few pages you can see.

If the integration token is correct and pages have been shared, Claude will list the accessible pages.

5 Workflows the Notion MCP Server Enables

Workflow 1: Writing Specs to Notion

After planning a feature in a Claude Code session, write the spec directly to a Notion page.

Based on our discussion about the notification preferences feature, 
write a technical spec to the "Feature Specs" database in Notion. 
Include: overview, data model changes, API endpoints needed, 
edge cases to handle, and open questions.

Claude reads your conversation context, structures the spec, and creates a new page in the specified Notion database. The result is a properly formatted spec page without any manual transcription from your terminal.

Workflow 2: Reading Notion Docs as Context

Pull documentation from Notion before starting a task to ground Claude in your team’s decisions.

Read the "Authentication Architecture" page from our Notion engineering wiki. 
Then read the "API Design Conventions" page. 
Now, using those as context, write the new OAuth token refresh endpoint.

Claude fetches both pages through the MCP server and uses their content as context before generating code. This is particularly valuable when the relevant decision history or conventions live in Notion but not in the codebase itself.

Workflow 3: Updating Project Status

Keep Notion project trackers current without switching out of your development environment.

The user dashboard feature is now complete and deployed to staging. 
Update the "Q2 Features" database in Notion to set the status of 
"User Dashboard" to "In Review" and add a note: deployed to staging on [today's date], 
ready for QA.

Claude finds the correct record in the Notion database and updates the status field and notes. This keeps project tracking current without requiring a context switch to the browser.

Workflow 4: Creating Bug Reports

When you encounter a bug during development, Claude can create a structured bug report in Notion directly.

Create a bug report in our Notion bug tracker database with the following:
- Title: Payment form validation not triggering on blur
- Severity: Medium
- Reproduction steps: [the steps I just described]
- Expected behavior: validation fires when user leaves an input field
- Actual behavior: validation only fires on form submit
- Affected component: PaymentForm.tsx

Claude creates a properly formatted record in the bug tracker with all fields populated. The report follows whatever structure your Notion database template uses.

Workflow 5: Documentation Sync

Keep Notion documentation aligned with code changes after a significant refactor or API change.

I just renamed the processPayment function to handlePaymentIntent and changed 
its signature. Read the "Payment Integration Guide" page in Notion and 
update any references to the old function name and signature.

Claude reads the Notion page, identifies references to the old function name, and updates them to match the new implementation. This prevents documentation from drifting out of sync after code changes.

Limits of the Notion MCP Server

The access control model is intentional. Claude can only see what you share with the integration. Pages not shared are completely invisible, which is a useful security property for workspaces where Claude should not access everything.

Frequently Asked Questions

Can Claude access all pages in my Notion workspace?

No. Claude can only access pages and databases that have been explicitly shared with your Notion integration. This is a Notion security feature. You must share each relevant page or database with the integration before Claude can see it. Child pages inherit the permission from their parent, so sharing a top-level section is usually the most efficient approach.

Can Claude read Notion databases with complex filters and sorts?

Yes. The MCP server supports Notion’s filter and sort API. You can ask Claude to query a database with specific criteria and it will use the appropriate API parameters. For example: “Show me all feature specs with status ‘In Progress’ sorted by last updated date.”

Will Claude overwrite content I have already written in Notion?

Claude will only modify content if you ask it to. When writing to a page, Claude typically appends content or updates specific fields rather than replacing everything. Be explicit in your prompt about what you want changed. For destructive operations, ask Claude to confirm before proceeding.

Is the Notion integration token the same as a Notion API key?

The Internal Integration Token is Notion’s equivalent of an API key for workspace integrations. It is different from OAuth tokens used by public Notion integrations. For Claude Code, the internal integration token is the correct credential to use.

Ready to connect Notion to your Claude Code workflow?

Follow the steps above to wire up your Notion workspace and start with the reading-docs-as-context workflow, it demonstrates the value immediately without requiring write access.

Path one: set it up yourself. Follow the integration creation steps, share your most-used pages, and expand into spec writing and documentation sync as you get comfortable. The Claude Code course covers MCP setup and workflow patterns in depth.

Path two: work with Phos AI Labs. If you want Notion integrated into a broader Claude Code workflow for an engineering or product team, including documentation sync automation and project tracking, we design and implement those systems. Phos AI Labs is a CCA-F certified Claude implementation partner. Thirty minutes, no deck. Start here.