Notion MCP Server: AI-Powered Workspace Management with Claude

TL;DR - Notion MCP Quick Start

Connect your AI to your Notion workspace - Manage pages, databases, and tasks with natural language.

🆕 2025: Notion launched official MCP support, AI Agents (Notion 3.0), and AI Meeting Notes! This is the most powerful Notion-AI integration yet. For an introduction to MCP, see the MCP Introduction guide.

Quick Setup:

1. Create Notion Integration: Go to notion.so/my-integrations
2. Share pages with your integration
3. Add config:

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

What you can do:

• 🔍 Search: Find pages and databases
• 📖 Read: Access page content and database entries
• ✏️ Create: Add new pages and content blocks
• 📊 Query: Filter and sort database data
• 🔄 Update: Modify existing pages and properties

Example conversation:

You: What tasks are due this week in my Task Database?

Claude: I found 5 tasks due this week:

        | Task              | Due Date | Priority | Status      |
        |-------------------|----------|----------|-------------|
        | Review PR #45     | Dec 26   | High     | In Progress |
        | Update docs       | Dec 27   | Medium   | Not Started |
        | Team standup prep | Dec 27   | Low      | Not Started |
        ...

💡 Note: Only pages you explicitly share with the integration are accessible.

🤖 Hosted Option: Notion now offers a hosted MCP server option - no local setup required!

Why Notion + AI is Powerful

Notion is already a “second brain” for millions. Adding AI makes it smarter:

Use Cases

For more productivity tips, see the AI for Everyday Productivity guide.

2025 AI Features

Prerequisites

1. Notion Account

Free or paid Notion account with workspace access.

2. Notion Integration (API Key)

Creating an Integration:

1. Go to notion.so/my-integrations
2. Click ”+ New integration”
3. Configure:
   • Name: “Claude MCP” (or your preference)
   • Workspace: Select your workspace
   • Capabilities: Choose based on needs

Capability Options:

4. Click “Submit”
5. Copy the Internal Integration Token (starts with secret_)

3. Share Pages with Integration

This is the most important step! Your integration can only access pages you explicitly share.

To share a page:

1. Open the page in Notion
2. Click “Share” (top right)
3. Click “Invite”
4. Search for your integration name
5. Click to add it

Share the parent page to grant access to all subpages.

Installation & Configuration

Claude Desktop Setup

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Alternative Package

There are community Notion MCP packages as well:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-notion"],
      "env": {
        "NOTION_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor Setup

Add to your project’s .cursor/mcp.json:

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

Verify Installation

Restart your AI client and test:

You: Search my Notion for pages about "project planning"

Claude: I found 3 pages matching "project planning":

        1. **Project Planning Guide**
           Last edited: Dec 20, 2024
           Type: Page
           
        2. **Q1 2025 Project Planning**
           Last edited: Dec 18, 2024
           Type: Page
           
        3. **Planning Templates Database**
           Last edited: Dec 15, 2024
           Type: Database

Available Tools

The Notion MCP server provides these capabilities:

Search & Discovery

Database Operations

Content Operations

Working with Notion Databases

Notion databases are powerful, and AI can query them naturally.

Understanding Database Structure

You: Describe my Tasks database

Claude: **Tasks Database Structure:**

        | Property      | Type          | Options                    |
        |---------------|---------------|----------------------------|
        | Task Name     | Title         | (required)                 |
        | Status        | Select        | Not Started, In Progress,  |
        |               |               | Blocked, Done              |
        | Priority      | Select        | High, Medium, Low          |
        | Assignee      | Person        | Team members               |
        | Due Date      | Date          | Date picker                |
        | Project       | Relation      | → Projects database        |
        | Estimated Hrs | Number        | 0-100                      |
        | Tags          | Multi-select  | Bug, Feature, Docs, etc.   |

Querying Databases

You: Show me all high-priority tasks that are not done, 
     sorted by due date

Claude: I'll query your Tasks database...

        **High Priority Active Tasks:**
        
        | Task                    | Status      | Due Date | Assignee |
        |-------------------------|-------------|----------|----------|
        | Fix authentication bug  | In Progress | Dec 26   | Alice    |
        | Review security audit   | Not Started | Dec 27   | Bob      |
        | Update API docs         | Blocked     | Dec 28   | Carol    |
        | Performance testing     | Not Started | Dec 30   | Alice    |
        
        4 tasks found, sorted by due date.

Complex Filters

You: Find tasks assigned to me that are either:
     - High priority, or
     - Overdue

Claude: Querying with compound filters...

        **Your Urgent Tasks:**
        
        | Task             | Priority | Due Date | Status      |
        |------------------|----------|----------|-------------|
        | API migration    | High     | Dec 28   | In Progress |
        | Bug fix #234     | Medium   | Dec 20   | Not Started | ⚠️ Overdue
        | Security patch   | High     | Dec 26   | Not Started |
        | Docs update      | Low      | Dec 15   | In Progress | ⚠️ Overdue
        
        2 overdue + 2 high priority = 4 urgent tasks

Content Management Workflows

Workflow 1: Meeting Notes Creation

You: Create a meeting notes page for today's product sync. 
     Include sections for attendees, agenda, discussion, 
     and action items.

Claude: Creating meeting notes page...

        ✅ Created: **Product Sync - December 24, 2024**
        
        Page structure:
        - 📋 Attendees: [empty - ready to fill]
        - 📌 Agenda
        - 💬 Discussion Notes
        - ✅ Action Items
        - 📅 Next Steps
        
        Page URL: [link to Notion page]
        
        Would you like me to add any specific agenda items?

You: Add these agenda items:
     1. Q4 review
     2. Q1 planning
     3. Team updates

Claude: Added agenda items:
        - [ ] Q4 review
        - [ ] Q1 planning  
        - [ ] Team updates
        
        Meeting notes ready!

Workflow 2: Task Management

You: Create a task in my Tasks database:
     - Title: "Review PR #145"
     - Priority: High
     - Due: Tomorrow
     - Tags: Code Review

Claude: Created task in your Tasks database:

        **Review PR #145**
        - Priority: 🔴 High
        - Status: Not Started
        - Due Date: December 25, 2024
        - Tags: Code Review
        
        Task URL: [link to task]

You: Actually, make that due in 2 days and add it to the 
     "Backend Sprint" project

Claude: Updated task:
        - Due Date: December 26, 2024
        - Project: Backend Sprint ✅

Workflow 3: Knowledge Base Search

You: Search my documentation for anything about authentication, 
     and summarize what I have documented

Claude: Searching your workspace for authentication docs...

        **Found 5 relevant pages:**
        
        1. **Authentication Overview** (Docs/Architecture)
           - Last updated: Nov 15
           - Covers: OAuth2, JWT, session management
           
        2. **Auth API Reference** (Docs/API)
           - Last updated: Dec 1
           - Covers: Endpoints, request/response formats
           
        3. **SSO Integration Guide** (Docs/Guides)
           - Last updated: Oct 20
           - Covers: SAML, Okta, Azure AD
           
        4. **Auth Troubleshooting** (Docs/Support)
           - FAQ and common issues
           
        5. **Security Best Practices** (Docs/Security)
           - Token handling, encryption
        
        **Summary:** Your auth documentation covers OAuth2/JWT architecture,
        API endpoints, SSO integrations (SAML, Okta, Azure AD), and 
        troubleshooting guides. Security best practices are documented 
        separately.
        
        Would you like me to read any of these in detail?

Workflow 4: Weekly Review Automation

You: Help me with my weekly review. Find all tasks I completed 
     this week and create a summary in my Weekly Reviews database.

Claude: Gathering your completed tasks...

        **Tasks Completed (Dec 18-24):**
        
        | Task                      | Completed  | Project     |
        |---------------------------|------------|-------------|
        | API endpoint refactor     | Dec 23     | Backend     |
        | Documentation update      | Dec 22     | Docs        |
        | Bug fix #231              | Dec 21     | Bug Fixes   |
        | Code review PR #142       | Dec 20     | Reviews     |
        | Sprint planning           | Dec 19     | Planning    |
        
        **Summary:** 5 tasks completed
        
        Creating weekly review entry...
        
        ✅ Created: **Weekly Review - Week 52**
        
        Added:
        - ✅ Completed tasks summary (5 items)
        - 📊 Breakdown by project
        - 📈 Productivity notes
        
        Would you like me to add wins, challenges, or next week goals?

Example Prompts

Search & Discovery

# General search
"Search my Notion for pages about marketing strategy"
"Find all pages edited in the last week"
"What databases do I have access to?"

# Specific pages
"Show me my Q4 planning document"
"Find the onboarding checklist"
"Where did I put my product roadmap?"

Database Queries

# Simple filters
"Show all tasks assigned to me"
"List open bugs in the Bug Tracker"
"Find high-priority items"

# Date-based queries
"What's due this week?"
"Show tasks completed yesterday"
"Find overdue items"

# Complex queries
"Tasks that are high priority OR overdue"
"Projects with no assigned owner"
"Completed tasks grouped by assignee"

Content Creation

# Pages
"Create a new meeting notes page for today"
"Add a new project to my Projects database"
"Create a blog post draft titled 'AI Trends 2025'"

# Adding content
"Add a summary section to my weekly review"
"Append these action items to the meeting notes"
"Add a table of contents to the documentation page"

# Templates
"Create a 1:1 meeting page from my template"
"Add a new sprint using my sprint template"

Updates & Modifications

# Status changes
"Mark task #234 as complete"
"Change the project status to 'In Progress'"
"Set all my overdue tasks to highest priority"

# Property updates  
"Update the due date to next Friday"
"Add the 'urgent' tag to this task"
"Assign this to Alice"

# Bulk operations
"Mark all tasks in 'Done' column as archived"
"Update status of all Q4 tasks to 'Closed'"

Reports & Analysis

# Status reports
"Give me a summary of project status"
"How many tasks are in each status?"
"What's my team's workload this week?"

# Progress tracking
"Compare completed tasks this week vs last week"
"Show my productivity trend over the month"
"List projects by completion percentage"

# Custom reports
"Create a sprint velocity report"
"Generate a client deliverables summary"

Advanced Configuration

Multiple Workspaces

If you have multiple Notion workspaces:

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

Then specify which workspace:

You: Using my work Notion, show me the sprint tasks
You: Check my personal Notion for grocery lists

Read-Only Access

For safety, create an integration with only read permissions:

1. Go to integration settings
2. Under Capabilities, only check:
   • ☑️ Read content
   • ☐ Update content
   • ☐ Insert content

Sharing Best Practices

Troubleshooting

Issue: “Could not find page”

Symptoms: AI can’t find or access a page

Solutions:

Issue: “Insufficient permissions”

Symptoms: Can search but can’t modify

Solutions:

Issue: “Rate limited”

Symptoms: Operations fail with rate limit error

Solutions:

• Wait a minute between heavy operations
• Use more specific queries
• Batch operations where possible

Issue: “Invalid block”

Symptoms: Can’t add certain content types

Solutions:

• Check if block type is supported
• Verify page has write access
• Some complex blocks not supported via API

Combining with Other MCPs

Notion + Filesystem

Save Notion content to files:

You: Export my "Product Requirements" page to a markdown file

Claude: [Uses Notion to read page]
        [Uses Filesystem to write file]
        
        Exported to: /projects/docs/product-requirements.md
        - 2,450 words
        - Includes 3 sections and 2 tables

Notion + GitHub

Sync documentation:

You: Find my API documentation in Notion and create a 
     GitHub issue for each TODO item found

Claude: [Uses Notion to search and read docs]
        [Uses GitHub to create issues]
        
        Found 4 TODO items in API docs:
        - Created Issue #56: "Add rate limiting section"
        - Created Issue #57: "Document error codes"
        - Created Issue #58: "Add authentication examples"
        - Created Issue #59: "Update response schemas"

Notion + Slack

Share updates with team:

You: Summarize this week's completed tasks and post to #team-updates

Claude: [Uses Notion to query completed tasks]
        [Uses Slack to post message]
        
        Posted to #team-updates:
        "🎉 This week's wins:
        - 8 tasks completed
        - 2 projects finished
        - 3 bugs squashed"

Notion + Memory

Remember context across sessions:

You: Learn my Notion structure so you can help me faster

Claude: [Uses Notion to explore workspace]
        [Uses Memory to store structure]
        
        I've memorized your workspace:
        - 5 main areas: Work, Personal, Projects, Docs, Archive
        - 12 databases
        - Key pages and their purposes
        
        I'll remember this for our future conversations!

Security Best Practices

Token Security

For more on AI security best practices, see the Understanding AI Safety, Ethics, and Limitations guide.

Access Control

Integration Management

To review your integrations:
1. notion.so/my-integrations
2. Click each integration
3. Check connected pages
4. Remove access if no longer needed

Related MCP Servers

Summary

The Notion MCP Server connects your AI to your workspace:

• ✅ Search across all shared pages and databases
• ✅ Query databases with natural language filters
• ✅ Create pages, tasks, and content blocks
• ✅ Update properties and content
• ✅ Control exactly what AI can access
• ✅ Agents (2025) - Autonomous multi-step workflows

2025 Highlights:

• Notion 3.0 with AI Agents for autonomous tasks
• AI Meeting Notes with transcription and summaries
• Enterprise Search across workspaces
• Hosted MCP server option (no local setup)
• AI database properties (smart autofill)

Best use cases:

• Task management and updates
• Meeting notes creation (now with AI transcription!)
• Knowledge base search
• Weekly reviews and reporting
• Documentation maintenance

Security checklist:

• ☐ Create dedicated integration for MCP
• ☐ Grant minimal required permissions
• ☐ Share only necessary pages
• ☐ Use read-only for sensitive content
• ☐ Periodically audit access

Next: Learn about Git MCP Server → for version control integration.

Questions about Notion MCP? Check the Notion API docs or the official MCP package.