notion-mcp-server
Allows reading, creating, searching, and managing Notion pages, databases, blocks, and comments. Supports markdown conversion, bulk operations, and productivity shortcuts like tasks and journaling.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@notion-mcp-server Search my Notion for 'machine learning'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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
Install with uv (recommended)
uv tool install notion-mcp-serverInstall 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
.envfile is needed when usinguvx; your token goes directly in the Claude config JSON (Step 3).
Step 1: Create a Notion Integration
Click "+ New integration"
Name it (e.g., "Claude MCP")
Select your workspace
Click Submit
Copy the Internal Integration Secret (starts with
secret_orntn_)
Step 2: Share Pages with Integration
For each page or database you want Claude to access:
Open the page in Notion
Click "..." menu (top right)
Click "Connections" → "Connect to"
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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonAdd 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.jsonto your.gitignoreif it contains yourNOTION_TOKEN, or use environment variable references and keep secrets in a local.envfile.
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/databasescheck_connection()— Verify integration works
📄 Page Operations
get_page(page_id_or_url)— Read page as markdowncreate_page(title, parent_id, content, privacy)— Create new pageappend_to_page(page_id_or_url, content)— Append contentupdate_page_title(page_id_or_url, new_title)— Rename pagearchive_page(page_id_or_url)— Soft-delete pagerestore_page(page_id_or_url)— Restore archived pageduplicate_page(page_id_or_url, new_title)— Clone page
🗂 Database Operations
list_databases()— List all databasesget_database_schema(database_id_or_url)— See columns and typesquery_database(database_id_or_url, filters, sort_by, ...)— Query rowsadd_database_row(database_id_or_url, properties, content)— Add rowupdate_database_row(page_id_or_url, properties)— Update rowbulk_add_rows(database_id_or_url, rows)— Add many rows at once
🧱 Block Operations
get_block_children(block_id_or_url)— Read all blocksupdate_block(block_id_or_url, new_content)— Edit a blockdelete_block(block_id_or_url)— Delete a block
💬 Comments
add_comment(page_id_or_url, comment_text)— Add a commentget_comments(page_id_or_url)— Read comments
⚡ Productivity Shortcuts
quick_note(content, title)— Quick note to default parentdaily_journal(entry)— Append timestamped entry to journaladd_task(title, due_date, priority, status, tags)— Smart-add taskget_today_tasks()— Tasks due today or overduecomplete_task(task_name_or_id)— Mark task doneget_recent_pages(limit)— Recently edited pageslearning_dashboard()— Learning progress overview
🎨 Markdown Support
Full bidirectional conversion:
Markdown | Notion Block |
| Heading 1 |
| Heading 2 |
| Heading 3 |
| Bulleted list |
| Numbered list |
| To-do (unchecked) |
| To-do (checked) |
| Quote block |
| Code block |
| Divider |
| Bold text |
| Italic text |
| Inline code |
| Link |
⚙️ Configuration
Environment Variable | Required | Description |
| ✅ Yes | Your integration secret |
| ❌ No |
|
| ❌ 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-mcpYour .env file:
NOTION_TOKEN=secret_your_token_here
DEFAULT_PRIVACY=private
DEFAULT_PARENT_PAGE_ID= # optionalThe
.envfile is only for local development. Regular users should use theenvblock 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
Available Tools
27 toolsadd_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
Scored across 27 tools
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 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.
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.
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
Related MCP Connectors
Streamline your Attio workflows using natural language to search, create, update, and organize com…
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
YouTube transcripts (chunks, phrase search, most replayed moments), PDFs and web pages as Markdown.
Create, search and manage Knowtis collaborative notes from AI assistants.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables interaction with Notion workspaces through the Notion API. Supports creating, retrieving, and updating Notion pages and their properties, allowing users to manage Notion content through natural language.4MIT
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Notion workspaces through the Notion API, allowing users to search, read, comment on, and create pages and databases using natural language commands.MIT
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Notion databases and pages via the Notion API. Allows searching, reading, and writing to Notion through natural language.MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language queries on your Notion workspace, with comprehensive search, page hierarchy mapping, and tools for reading and writing Notion pages.MIT