MCP Library updated 18 min read

Notion MCP Server: Manage Your Workspace with AI

Connect Notion to AI assistants. Learn how to search pages, query databases, create content, and automate workspace management using natural language.

Rajesh Praharaj

· Updated

Contents 15 sections
  1. TL;DR - Notion MCP Quick Start
  2. Why Notion + AI is Powerful
  3. Prerequisites
  4. Installation & Configuration
  5. Available Tools
  6. Working with Notion Databases
  7. Content Management Workflows
  8. Example Prompts
  9. Advanced Configuration
  10. Troubleshooting
  11. Combining with Other MCPs
  12. Security Best Practices
  13. Related MCP Servers
  14. Summary
  15. Frequently Asked Questions

TL;DR - Notion MCP Quick Start

Connect your AI to your Notion workspace - Manage pages, databases, and tasks with natural language using Notion’s official @notionhq/notion-mcp-server package and the hosted OAuth endpoint at https://mcp.notion.com/mcp documented at Notion MCP Documentation. By converting deeply nested Notion block JSON responses into clean Markdown before returning them to the LLM, the official Notion MCP server cuts context token consumption by 75% to 85% (averaging 900 tokens per page versus 4,800+ raw JSON block tokens) across frontier models on our LLM Benchmarks. Draft structured PRDs with our AI PRD Generator and validate your MCP config with our JSON Formatter & Validator.

2026 Official @notionhq/notion-mcp-server & Hosted mcp.notion.com Summary
  • Hosted OAuth vs Local Stdio: Connect zero-config via OAuth 2.1 to https://mcp.notion.com/mcp (or SSE at https://mcp.notion.com/sse), or run npx -y @notionhq/notion-mcp-server locally with an Internal Integration Token (ntn_...).
  • Markdown Conversion Layer: Automatically serializes Notion block hierarchies into Markdown, enabling multi-page specification synthesis without exhausting context windows.
  • Rate Limits & Access Control: Notion enforces an average rate limit of 3 requests per second per integration token (Notion Request Limits), and integrations can only read or edit pages explicitly connected via the page Connections menu.

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:

Manual NotionWith Notion MCP
Navigate through pages”Find my meeting notes from last week”
Filter database views manually”Show overdue high-priority tasks”
Copy-paste into AI for helpAI reads pages directly
Create pages through UI”Create a meeting notes page for today”
Update properties one by one”Mark all completed tasks as Done”

Use Cases

WhoHow They Use It
Project ManagersQuery tasks, update statuses, generate reports
WritersSearch research, organize notes, create outlines
DevelopersAccess documentation, update specs, manage tickets
StudentsSearch notes, organize study materials, track assignments
TeamsShare context with AI, automate updates, sync information

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

2025 AI Features

FeatureDescription
Notion 3.0 AgentsAutonomous AI that executes multi-step workflows
AI Meeting NotesReal-time transcription with summaries and action items
Enterprise SearchUnified discovery across Notion and external tools
AI Database PropertiesSmart autofill, AI summaries, AI keywords

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:

CapabilityWhat It Allows
Read contentRead pages and databases
Update contentModify existing content
Insert contentCreate new pages and blocks
Read commentsAccess page comments
  1. Click “Submit”
  2. 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

ToolDescriptionExample Prompt
searchSearch all accessible content”Find pages about marketing”
list_databasesShow all databases”What databases do I have?”
get_pageRead a specific page”Show me my weekly review page”

Database Operations

ToolDescriptionExample Prompt
query_databaseFilter and get entries”Show overdue tasks”
get_database_schemaGet properties and types”What fields does my Tasks database have?”

Content Operations

ToolDescriptionExample Prompt
create_pageCreate a new page”Create a meeting notes page”
update_pageModify page properties”Mark this task as complete”
append_blocksAdd content to a page”Add a summary section to this doc”
get_block_childrenRead page content”What’s in this page?”

Working with Notion Databases

Notion databases act as structured operational data stores for sprint backlogs, product roadmaps, CRM pipelines, and engineering RFC registries. Through the Notion MCP server, your AI assistant can first inspect a database’s property schema (title, select, multi_select, status, date, people, and relation columns) and then construct compound JSON filter and sort payloads automatically from plain English queries. Because the Notion REST API returns up to 100 items per paginated query at a rate limit of 3 requests/second, filtering by explicit status and date bounds on the server side ensures fast, low-token responses.

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

Automating Notion content workflows with an MCP-enabled AI assistant eliminates the manual friction of formatting meeting notes, triaging sprint tasks, synthesizing scattered engineering specs, and compiling weekly status reports. When creating or appending blocks to a Notion page, @notionhq/notion-mcp-server translates standard Markdown headings, bulleted lists, to-do checkboxes, and code blocks into native Notion block objects (heading_2, bulleted_list_item, to_do, code). Below are four end-to-end workflows showing how product managers and engineers automate daily workspace operations.

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 ✅
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

ScopeHow to Set Up
Entire workspaceShare workspace root page
Specific areaShare parent page of that area
Single databaseShare just that database
Read-onlyUse read-only integration

Troubleshooting

Issue: “Could not find page”

Symptoms: AI can’t find or access a page

Solutions:

CauseSolution
Page not sharedShare page with integration
Wrong workspaceCheck integration workspace
Page deletedVerify page exists
Caching delayWait a few minutes, try again

Issue: “Insufficient permissions”

Symptoms: Can search but can’t modify

Solutions:

CauseSolution
Read-only integrationEnable write capabilities
Page lockedCheck page permissions in Notion
Database restrictionsVerify database sharing settings

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

Connecting Notion MCP with local filesystem tools, GitHub repositories, Slack channels, and persistent Memory MCP servers bridges the gap between product documentation and live code execution. As we discuss in Context Engineering for AI Agents, engineering teams lose hours every week manually copying acceptance criteria from Notion PRDs into GitHub issues and Slack standup threads. With multi-server MCP orchestration, your AI assistant can read a Notion specification, generate corresponding GitHub issues, export Markdown docs to your repository, and post a sprint summary to Slack in a single turn.

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

Notion’s integration permission model is built on explicit page-level and database-level sharing: an Internal Integration Token (ntn_...) has zero access to any workspace content until a user explicitly connects that integration to a specific parent page or database via the top-right Connections menu. To maintain strict least-privilege governance, create separate Notion integrations for read-only knowledge base search versus active task creation, never share your workspace root page with an AI integration, and periodically audit connected pages at notion.so/my-integrations.

Token Security

✓ Do✗ Don’t
Store token in env variablesHardcode in config files
Use separate integrationsShare one token
Grant minimal permissionsEnable all capabilities
Rotate tokens periodicallyKeep stale tokens active
Revoke unused integrationsLeave old integrations active

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

Access Control

PracticeWhy
Share specific pagesLimits AI access scope
Use read-only for sensitivePrevents accidental changes
Separate work/personalDifferent integrations, different access
Audit shared pagesRegularly review what’s accessible

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

ServerComplements Notion By…
Filesystem MCPExporting Notion content
GitHub MCPSyncing docs to repos
Slack MCPSharing Notion updates
Memory MCPRemembering workspace context

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.

Frequently Asked Questions

What can Notion MCP do?

Notion MCP lets AI assistants search your workspace, read pages and databases, create new pages, update content, and query database entries. In 2025, it integrates with Notion's AI Agents for autonomous multi-step workflows.

How do I get a Notion API key?

Go to notion.so/my-integrations, create a new integration, and copy the Internal Integration Token. Then share your desired pages/databases with the integration for access.

Can AI access all my Notion pages?

No, only pages and databases you explicitly share with your integration. This gives you fine-grained control over what AI can see and modify.

Can AI create new pages?

Yes! AI can create new pages in any database or as subpages of pages shared with the integration. It can also add content blocks like text, headings, lists, and more.

Is it safe to give AI access to my Notion?

Yes, when configured properly. You control exactly which pages the integration can access, and you can revoke access anytime. Use read-only access for sensitive workspaces.

Can AI query my Notion databases?

Absolutely! AI can filter, sort, and search your databases using natural language. Ask 'show me overdue tasks' or 'find high-priority projects' and AI will query accordingly.

Does it work with Notion formulas and relations?

AI can read formula results and follow relations. However, complex formulas are computed by Notion, and AI sees the final values.

Can I use this with team workspaces?

Yes! Create an integration in your team workspace and share the necessary pages with it. In 2025, Notion added Enterprise Search for unified discovery across workspaces.

Written by Rajesh Praharaj

Product Leader & AI Builder

Product leader and AI builder focused on practical LLM systems, Model Context Protocol (MCP) integrations, agentic workflows, and free browser-based tools for product & engineering teams.

Was this page helpful?

Let us know if you found what you were looking for.