Provides markdown-first tools for managing Notion workspaces, including page lifecycle operations (create, update, archive, duplicate), database management with bulk operations, block-level editing, user management, workspace search, and comment operations. Features composite actions that combine multiple operations, auto-pagination, and smart database queries.
Click on "Install 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., "@Better Notion MCPcreate a new page in my 'Projects' database with title 'Q4 Planning' and markdown content for our quarterly goals"
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.
Better Notion MCP
Markdown-First MCP Server for Notion - Optimized for AI Agents
Why "Better"?
7 mega action-based tools that consolidate Notion's 28+ REST API endpoints into composite operations optimized for AI agents.
vs. Official Notion MCP Server
Feature | Better Notion MCP | Official Notion MCP |
Content Format | Markdown (human-readable) | Raw JSON blocks (verbose) |
Operations | Composite actions (create page + content + properties in 1 call) | Atomic operations (2+ separate calls required) |
Pagination | Auto-pagination (transparent) | Manual cursor management |
Bulk Operations | Native batch support (create/update/delete multiple items at once) | Loop through items manually |
Tool Architecture | 7 mega action-based tools (30+ actions) | 28+ individual endpoint tools |
Database Query | Smart search (auto-detect best match) | Manual filters + sorts required |
Token Efficiency | Optimized for AI context | Standard API responses |
Setup | Simple (NOTION_TOKEN only) | OAuth flow or token |
Installation
Get your Notion token: https://www.notion.so/my-integrations → Create integration → Copy token → Share pages with integration
Quick Start
NPX (Recommended)
Docker
Tools Overview
7 mega tools with 30+ actions:
Composite Actions: Combine operations (e.g., create page + content + properties in 1 call)
Auto-Pagination: Transparent handling of large datasets
Bulk Operations: Process multiple items efficiently
Smart Search: Auto-detect best matches in database queries
Token Optimization (v2)
~77% token reduction via tiered descriptions:
Tier | Purpose | Token Cost |
Tier 1 | Compressed descriptions (always loaded) | ~340 tokens |
Tier 2 | Full docs via | ~1,500 tokens |
Tier 3 | MCP Resources (for supported clients) | Same as Tier 2 |
Usage:
Client Compatibility:
Claude Desktop, VS Code Copilot: Full support (Tier 1 + 2 + 3)
Cursor, Windsurf: Via
helptool (Tier 1 + 2)
Limitations
Supported Block Types (Markdown Conversion):
✅ Headings (H1-H3), Paragraphs, Lists (bulleted/numbered)
✅ Code blocks, Quotes, Dividers
✅ Inline formatting (bold, italic, code, strikethrough, links)
Unsupported Block Types:
❌ Tables, Toggles, Callouts, Columns
❌ Databases, Embeds, Images, Files
❌ Synced blocks, Templates
Build from Source
Prerequisites: mise only.
Available Commands
Contributing
Contributions welcome! See CONTRIBUTING.md for:
Development workflow (verified via CI)
Commit convention (enforced via git hooks)
Testing and code quality standards
License
MIT License - See LICENSE
Star this repo if you find it useful! ⭐