Claude Code Notion MCP: The Complete Setup Guide

If you're already using Claude Code to build and ship software faster, there's a natural next step that most developers overlook: connecting it directly to your Notion workspace. The Claude Code Notion MCP integration lets your AI agent read, create, update, and search your Notion pages and databases without ever leaving the terminal. No copy-pasting meeting notes. No manually creating tickets. No switching tabs to log a bug.

This guide covers everything you need: what the Notion MCP server is, why it matters for developer workflows, step-by-step setup instructions, the full configuration JSON, and practical use cases you can start using today.

What Is the Notion MCP Server?

The Notion MCP Server is an integration that connects Claude Code to your Notion workspace via the Model Context Protocol (MCP), the open standard created by Anthropic that allows AI agents to communicate with external services and data sources.

MCP has seen explosive growth since its launch. According to MCP Manager's adoption report, MCP server downloads grew from just under 100,000 in November 2024 to over 8 million by April 2025, an 80x increase in less than six months. The ecosystem now includes over 5,800 MCP servers, and major platforms including OpenAI, Google, and Microsoft have all adopted the protocol. If you want to understand what makes MCP so powerful for developers, building a custom MCP server to encode your own expertise is one of the fastest ways to see the protocol's full potential in action.

As Dhanji R. Prasanna, Chief Technology Officer at Block, put it: "Open technologies like the Model Context Protocol are the bridges that connect AI to real-world applications, ensuring innovation is accessible, transparent, and rooted in collaboration."

The Notion MCP Server is one of the most practically useful integrations in that ecosystem. Once configured, Claude Code can:

• Read and search pages and databases across your workspace
• Create new pages and database entries programmatically
• Update existing content based on code analysis or prompts
• Query database views with filters and sorting
• Manage comments and discussions
• Perform full CRUD operations on any Notion content

This turns Claude Code into a genuine project management agent, not just a code assistant.

Why Connect Claude Code to Notion?

Notion has become the operating system for product and engineering teams. According to Notion productivity research, over 50% of Fortune 500 companies now use Notion, and users report 87% higher task completion rates compared to traditional tools. The platform crossed $500 million in annualized revenue in 2025.

The problem is the context switch. Every time you find a bug, identify a missing feature, or want to log a decision, you have to leave your coding environment and open Notion manually. The Notion MCP integration eliminates that friction entirely.

Instead of stopping to create a ticket, you prompt Claude Code: "Create a bug ticket in our Issues database for the null pointer exception in the auth module." Claude Code reads your workspace, finds the right database, and creates a properly formatted entry, while you stay focused on the code. If you're still deciding which AI coding environment to build in, the Claude Code vs Cursor comparison breaks down when each tool gives you the most leverage.

Step-by-Step: How to Set Up the Notion MCP Server with Claude Code

The setup takes about ten minutes. Here is the complete process.

Step 1: Create a Notion Integration

Go to https://www.notion.so/my-integrations and click New integration.

• Give it a descriptive name (e.g., "Claude Code Agent")
• Select your workspace
• Choose Internal as the integration type
• Under capabilities, enable Read content, Update content, and Insert content
• Click Submit

After submitting, you'll see your Internal Integration Secret, this is your API token. Copy it and store it securely. You will not see it again unless you regenerate it.

Step 2: Share Pages and Databases with the Integration

Notion integrations only have access to pages you explicitly share with them. For each database or page you want Claude Code to access:

1. Open the page in Notion
2. Click the ... menu in the top right
3. Select Connect to and choose your integration

Repeat this for every database Claude Code will need to interact with, your task board, bug tracker, project wiki, meeting notes, and so on.

Step 3: Add the Notion MCP Server to Claude Code

Open your Claude Code MCP configuration file at ~/.claude/claude_desktop_config.json and add the following:

{
 "mcpServers": {
 "notion": {
 "command": "npx",
 "args": ["-y", "@notionhq/notion-mcp-server"],
 "env": {
 "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer your-notion-api-token-here\", \"Notion-Version\": \"2022-06-28\"}"
 }
 }
 }
}

Replace your-notion-api-token-here with the Internal Integration Secret from Step 1.

If you already have other MCP servers configured, add the "notion" block alongside them inside the "mcpServers" object:

{
 "mcpServers": {
 "figma": {
 "command": "npx",
 "args": ["-y", "figma-developer-mcp", "--stdio"],
 "env": {
 "FIGMA_ACCESS_TOKEN": "your-figma-token"
 }
 },
 "notion": {
 "command": "npx",
 "args": ["-y", "@notionhq/notion-mcp-server"],
 "env": {
 "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer your-notion-api-token-here\", \"Notion-Version\": \"2022-06-28\"}"
 }
 }
 }
}

The Figma example above is just one possibility, you can follow the same pattern to add any MCP server. The Figma MCP Claude Code setup guide walks through that specific integration if you want to connect your design system alongside Notion.

Step 4: Restart Claude Code and Verify

Restart Claude Code completely to pick up the new MCP configuration. Then verify the connection by asking:

Search my Notion workspace for any pages related to "project roadmap".

If the integration is working, Claude Code will return matching pages from your workspace. If you see an error, double-check that the API token is correct and that the relevant pages have been shared with your integration.

Practical Use Cases for the Notion MCP Integration

Here are the workflows that deliver the most immediate value.

Automated Bug Ticket Creation

During a code review session, prompt Claude Code to analyze a module and generate bug tickets:

Analyze the authentication module in src/auth/. For each bug or potential
issue you identify, create a new entry in my Notion Issues database with
the title, description, severity, and affected file path.

Claude Code reads the code, identifies issues, and populates your Notion database, with full context it pulled directly from the source.

Sprint Board Management

At the end of a planning session, have Claude Code translate your code comments and TODOs into structured tasks:

Search the codebase for all TODO and FIXME comments. Create a task in
my Sprint Board database for each one, assigning it to the appropriate
category based on the file location.

Documentation Syncing

Keep your Notion project wiki in sync with your actual codebase structure:

Read the README files in each top-level directory of this project and
update the corresponding pages in my Notion Architecture Wiki to reflect
the current structure.

Meeting Notes to Action Items

After a standup or planning call, paste your raw notes into a prompt:

Here are my meeting notes: [paste notes]. Create a structured meeting
notes page in Notion under the "Engineering Meetings" database, and
create individual task entries for each action item identified.

AI-Powered Content Pipelines

For teams building content or documentation at scale, the Notion MCP integration enables end-to-end pipelines where Claude Code reads a content brief from Notion, generates a draft, and writes it back, all in a single automated workflow.

Tips for Getting the Best Results

Be specific about which database to use. Notion workspaces can grow large. The more specific you are about the target database or page, the more accurately Claude Code will route the operation. Use the exact database name from your workspace.

Share only what you need. You don't need to give the integration access to your entire workspace. Start with the databases you actively want to automate, and expand access incrementally as you discover new use cases.

Use filters in queries. When searching or reading databases, provide filters to keep the results focused: "Find all tasks in the Sprint Board with Status = 'In Progress' and Assignee = 'Jules'." Unfiltered queries on large databases can return too much data for Claude Code to process efficiently.

Combine with other MCP servers. The Notion MCP Server works alongside other MCP integrations. A particularly powerful combination is Notion MCP + GitHub MCP, Claude Code can read a GitHub issue, analyze the relevant code, and create a detailed Notion task, all in one prompt. Another high-value pairing is Notion MCP alongside the Playwright MCP server for browser automation, which lets Claude Code verify live UI behavior and log findings directly into your Notion task tracker.

Test with read-only operations first. Before running prompts that create or update content at scale, start with search and read operations to confirm Claude Code is targeting the right databases. This prevents accidental data pollution in your workspace.

Use Plan Mode for complex multi-step workflows. When you're orchestrating a workflow that touches multiple Notion databases or involves conditional logic, enable Claude Code Plan Mode first. Planning before execution dramatically reduces errors when the agent is writing across several databases in a single session.

Start Building Smarter Workflows with Claude Code

The Notion MCP Server turns Claude Code from a coding assistant into a full project management agent. When your AI can read your sprint board, create tickets from code analysis, and sync documentation automatically, the productivity compounding effect is significant, you spend more time building and less time managing.

The setup takes ten minutes. The workflows you unlock last for the lifetime of every project that follows.

If you want to go deeper on Claude Code, including how to configure multiple MCP servers, write production-ready prompts, and build AI agents that automate entire workflows, explore the How to Master Claude Code: Ship Code Faster & Build AI Agents course. It covers MCP server setup and advanced automation in detail, with hands-on lessons you can apply immediately to your own projects.