Skip to main content
Glama
notion-mcp-server

notion-mcp-server

Notion MCP Server

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

PyPI version Python 3.10+ License: MIT MCP

✨ 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

Related MCP server: Notion MCP Server

🎬 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

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:

Markdown

Notion Block

# Heading 1

Heading 1

## Heading 2

Heading 2

### Heading 3

Heading 3

- bullet

Bulleted list

1. numbered

Numbered list

- [ ] todo

To-do (unchecked)

- [x] done

To-do (checked)

> quote

Quote block

```code```

Code block

---

Divider

**bold**

Bold text

*italic*

Italic text

`inline code`

Inline code

[link](url)

Link

⚙️ Configuration

Environment Variable

Required

Description

NOTION_TOKEN

✅ Yes

Your integration secret

DEFAULT_PRIVACY

❌ No

private (default) or public

DEFAULT_PARENT_PAGE_ID

❌ No

Default parent for new pages

💡 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:

⭐ 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

Available Tools

27 tools
add_commentC

Add a comment to a Notion page.

Inputs: page_id_or_url (required), comment_text (required). Returns: object

add_database_rowC

Add a new row to a database.

Inputs: database_id_or_url (required), properties (required), content. Returns: object

add_taskC

Quick-add a task to your Tasks database (auto-detected). Date format: 'YYYY-MM-DD'

Inputs: title (required), due_date, priority, status, +1 more. Returns: object

append_to_pageC

Append markdown content to an existing page.

Inputs: page_id_or_url (required), content (required). Returns: object

archive_pageB

Archive (soft-delete) a Notion page.

Inputs: page_id_or_url (required). Returns: object

bulk_add_rowsC

Add multiple rows to a database at once.

Inputs: database_id_or_url (required), rows (required). Returns: object

check_connectionB

Verify Notion integration is working.

Inputs: no named parameters. Returns: object

complete_taskB

Mark a task as complete by name or ID.

Inputs: task_name_or_id (required). Returns: object

create_pageC

Create a new Notion page with markdown content.

Inputs: title (required), parent_id, content, privacy. Returns: object

daily_journalA

Add a timestamped entry to today's journal. Auto-finds a page with 'journal' in the title.

Inputs: entry (required), journal_keyword. Returns: object

delete_blockC

Delete a single block from a page.

Inputs: block_id_or_url (required). Returns: object

duplicate_pageC

Duplicate a page (creates a copy with same content).

Inputs: page_id_or_url (required), new_title. Returns: object

get_block_childrenC

Get all children blocks of a block (page or container).

Inputs: block_id_or_url (required). Returns: object

get_commentsC

Get all comments on a page.

Inputs: page_id_or_url (required). Returns: object

get_database_schemaB

Get the schema (columns/properties) of a database. Use this BEFORE adding/updating rows to know property names and types.

Inputs: database_id_or_url (required). Returns: object

get_pageB

Read a Notion page's full content as markdown.

Inputs: page_id_or_url (required). Returns: object

get_recent_pagesC

Get recently edited pages.

Inputs: limit. Returns: object

get_today_tasksA

Get all tasks due today or overdue.

Inputs: no named parameters. Returns: object

learning_dashboardA

Get a dashboard view of your AI/ML learning progress. Shows topics by status, category, priority, and average progress.

Inputs: no named parameters. Returns: object

list_databasesA

List all Notion databases accessible to the integration.

Inputs: no named parameters. Returns: object

query_databaseC

Query a database with filters and sorting.

Filter examples: {"Status": "Learning"} {"Priority": "🔥 Critical", "Category": "ML"} {"Progress": {"greater_than": 50}}

Inputs: database_id_or_url (required), filters, sort_by, sort_order, +1 more. Returns: object

quick_noteB

Save a quick note to your default parent page. Requires DEFAULT_PARENT_PAGE_ID in .env.

Inputs: content (required), title. Returns: object

restore_pageB

Restore an archived page.

Inputs: page_id_or_url (required). Returns: object

search_notionC

Search Notion for pages and databases by keyword.

Inputs: query, filter_type, limit. Returns: object

update_blockC

Update a single block's text content (for edits).

Inputs: block_id_or_url (required), new_content (required). Returns: object

update_database_rowC

Update properties of an existing database row.

Inputs: page_id_or_url (required), properties (required). Returns: object

update_page_titleC

Rename a Notion page.

Inputs: page_id_or_url (required), new_title (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 27 tools

    Disambiguation4/5

    Most tools have distinct purposes, but some overlap exists (e.g., create_page, append_to_page, quick_note all add content; add_database_row and bulk_add_rows differ only in count). Descriptions help resolve ambiguity.

    Naming Consistency3/5

    Naming mixes patterns: get_ for retrieval, add_/create_ for creation, but also daily_journal, learning_dashboard, quick_note break the verb_noun pattern. Consistency within groups but variation overall.

    Tool Count3/5

    27 tools is on the high side for a single server, potentially overwhelming. However, Notion's feature set is broad, so the count is somewhat justified but still feels heavy.

    Completeness4/5

    Covers most core Notion operations: CRUD for pages and database rows, comments, search, tasks, and specialized dashboards. Missing explicit delete row and full page delete, but archive serves as soft delete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers