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.
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:
Tool | Actions | Description |
pages |
,
,
,
,
,
| Complete page lifecycle with markdown support |
databases |
,
,
,
,
,
,
,
,
| Database management with bulk operations |
blocks |
,
,
,
,
| Granular block-level editing |
users |
,
,
,
| User management and discovery |
workspace |
,
| Workspace-wide operations |
comments |
,
| Comment operations with threading |
content_convert |
,
| Format conversion utility |
Key Features:
Markdown-First: Natural language content format
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
Development
Build from Source
Prerequisites: mise for managing Node.js and pnpm versions.
Available Commands
See CONTRIBUTING.md for full development workflow.
Contributing
Contributions welcome! See CONTRIBUTING.md for:
Development workflow with changesets
Commit convention (enforced via git hooks)
Testing and code quality standards
License
MIT License - See LICENSE
Star this repo if you find it useful! ⭐