Notion MCP Server

🚀 Powerful Notion integration for Claude — read, create, search, and manage your entire Notion workspace through natural language.

✨ Features

• 🔍 Smart Search — Find pages and databases instantly

• 📄 Page Management — Create, read, update, archive, duplicate pages

• 🎨 Full Markdown Support — Seamless markdown ↔ Notion blocks conversion

• 🗂 Database Operations — Query with filters, sort, bulk add rows

• ⚡ Productivity Shortcuts — Quick notes, daily journal, task management

• 🧱 Block-Level Control — Read, update, delete individual blocks

• 💬 Comments Support — Add and read page comments

• 🎓 Learning Dashboard — Track AI/ML or any learning database progress

• 🔒 Privacy First — All pages private by default

• ⚡ Fast & Async — Built with FastMCP, schema caching, auto-retry

🎬 What You Can Do

Ask Claude things like:

• "Search my Notion for 'machine learning'"

• "Create a page called 'Project Plan' with a roadmap"

• "Add 20 AI/ML topics to my Topics database"

• "Show me all tasks marked Critical priority"

• "What's on my schedule today?"

• "Add a quick note: meeting was great"

• "Show my learning dashboard"

📦 Installation

Prerequisites

• Python 3.10 or higher

• A Notion account

• Claude Desktop, Claude Code, or any MCP-compatible client

Install with uv (recommended)

uv tool install notion-mcp-server

Install with pip

pip install notion-mcp-server

🔧 Setup (5 minutes)

Each user needs their own Notion integration token. Tokens are personal — they grant access only to the pages you explicitly share with your integration. No .env file is needed when using uvx; your token goes directly in the Claude config JSON (Step 3).

Step 1: Create a Notion Integration

1. Go to notion.so/my-integrations

2. Click "+ New integration"

3. Name it (e.g., "Claude MCP")

4. Select your workspace

5. Click Submit

6. Copy the Internal Integration Secret (starts with secret_ or ntn_)

Step 2: Share Pages with Integration

For each page or database you want Claude to access:

1. Open the page in Notion

2. Click "..." menu (top right)

3. Click "Connections" → "Connect to"

4. Select your integration

💡 Pro tip: Sharing a parent page automatically gives access to all sub-pages. Create one "Workspace Hub" page and share that.

Step 3: Configure Claude Desktop

Mac/Linux:

~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "notion": {
      "command": "uvx",
      "args": ["notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "secret_your_token_here",
        "DEFAULT_PRIVACY": "private",
        "DEFAULT_PARENT_PAGE_ID": "optional_parent_page_id"
      }
    }
  }
}

🗂 Alternative: Project-level Setup via .mcp.json

Instead of editing the global Claude Desktop config, you can enable the Notion MCP server per-project by adding a .mcp.json file to the root of any codebase. This is ideal for team projects or when you want the server scoped to a specific workspace.

Create .mcp.json in your project root:

{
  "mcpServers": {
    "notion": {
      "command": "uvx",
      "args": ["notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "secret_your_token_here",
        "DEFAULT_PRIVACY": "private",
        "DEFAULT_PARENT_PAGE_ID": "optional_parent_page_id"
      }
    }
  }
}

💡 Tip: Add .mcp.json to your .gitignore if it contains your NOTION_TOKEN, or use environment variable references and keep secrets in a local .env file.

Supported by Claude Code, Cursor, Windsurf, and other MCP-compatible editors that respect project-level config files.

Step 4: Restart Claude Desktop

Fully quit (including system tray) and reopen.

Step 5: Test It!

Ask Claude:

"Check my Notion connection"

If you see ✅ Connected — you're all set!

🛠 Available Tools (22 Total)

🔍 Search & Connection

• search_notion(query, filter_type, limit) — Search pages/databases

• check_connection() — Verify integration works

📄 Page Operations

• get_page(page_id_or_url) — Read page as markdown

• create_page(title, parent_id, content, privacy) — Create new page

• append_to_page(page_id_or_url, content) — Append content

• update_page_title(page_id_or_url, new_title) — Rename page

• archive_page(page_id_or_url) — Soft-delete page

• restore_page(page_id_or_url) — Restore archived page

• duplicate_page(page_id_or_url, new_title) — Clone page

🗂 Database Operations

• list_databases() — List all databases

• get_database_schema(database_id_or_url) — See columns and types

• query_database(database_id_or_url, filters, sort_by, ...) — Query rows

• add_database_row(database_id_or_url, properties, content) — Add row

• update_database_row(page_id_or_url, properties) — Update row

• bulk_add_rows(database_id_or_url, rows) — Add many rows at once

🧱 Block Operations

• get_block_children(block_id_or_url) — Read all blocks

• update_block(block_id_or_url, new_content) — Edit a block

• delete_block(block_id_or_url) — Delete a block

💬 Comments

• add_comment(page_id_or_url, comment_text) — Add a comment

• get_comments(page_id_or_url) — Read comments

⚡ Productivity Shortcuts

• quick_note(content, title) — Quick note to default parent

• daily_journal(entry) — Append timestamped entry to journal

• add_task(title, due_date, priority, status, tags) — Smart-add task

• get_today_tasks() — Tasks due today or overdue

• complete_task(task_name_or_id) — Mark task done

• get_recent_pages(limit) — Recently edited pages

• learning_dashboard() — Learning progress overview

🎨 Markdown Support

Full bidirectional conversion:

⚙️ Configuration

💡 Examples

Example 1: Bulk Create Database Entries

"Add 20 AI/ML topics to my Topics database with appropriate categories and priorities"

Claude uses bulk_add_rows to create all 20 entries with one command.

Example 2: Daily Workflow

You: "What tasks do I have today?"
Claude: [shows your today_tasks]

You: "Mark 'Review PR #123' as done"
Claude: [calls complete_task]

You: "Add a journal entry: Productive day, finished 5 tasks"
Claude: [appends to journal page]

Example 3: Smart Querying

"Show me high-priority topics that aren't started yet, sorted by category"

Claude builds a complex filter and returns organized results.

🐛 Troubleshooting

"Object not found" errors

The page/database isn't shared with your integration. Fix: Open page → ... → Connections → Connect to your integration.

Empty search results

You haven't shared any pages with the integration yet. Fix: Share at least one page (and its sub-pages will inherit access).

"Cannot create workspace-level page"

Internal integrations can't create pages at workspace root. Fix: Set DEFAULT_PARENT_PAGE_ID in your config to a parent page.

Rate limit errors

Notion API allows ~3 requests/second. Fix: Server has built-in auto-retry with exponential backoff.

🧑‍💻 Local Development Setup

If you're contributing or want to run from source, use a .env file instead of the config JSON:

git clone https://github.com/KuldeepJha5176/notion-mcp-server
cd notion-mcp-server
cp .env.example .env
# Edit .env and add your NOTION_TOKEN
uv sync
uv run notion-mcp

Your .env file:

NOTION_TOKEN=secret_your_token_here
DEFAULT_PRIVACY=private
DEFAULT_PARENT_PAGE_ID=   # optional

The .env file is only for local development. Regular users should use the env block in the Claude config JSON as shown in Step 3.

🤝 Contributing

Pull requests welcome! For major changes, please open an issue first.

git clone https://github.com/KuldeepJha5176/notion-mcp-server
cd notion-mcp-server
uv sync
uv run pytest

🔒 Security

• Each user provides their own Notion token

• Tokens stored locally in user's environment

• Server never collects, stores, or transmits user data

• All communication is direct: User → Notion API

• See SECURITY.md for vulnerability reporting

📄 License

MIT — see LICENSE file.

🙏 Acknowledgments

Built with:

• FastMCP — Excellent MCP framework

• notion-client — Notion Python SDK

• Anthropic MCP — The protocol that makes it possible

⭐ Show Your Support

If this server helps you, please:

• ⭐ Star this repo

• 🐦 Tweet about it

• 📝 Blog about how you use it

• 🐛 Report bugs to make it better

Made with ❤️ for the Claude community by Kuldeep Jha