Better Notion MCP is a Markdown-first MCP server that provides AI-optimized, composite tools for interacting with Notion workspaces through human-readable markdown instead of raw JSON blocks.
Core Capabilities:
Pages: Create, read, update, archive, restore, and duplicate pages with markdown content; set titles, icons, covers, and properties; append or prepend content; batch operations
Databases: Create and manage databases with custom schemas; query with filters, sorts, and text search; create, update, and delete database pages; manage data sources; bulk operations
Blocks: Get, append, update, and delete individual blocks; supports headings, paragraphs, lists, code blocks, quotes, dividers, and inline formatting
Users: List all users, get specific user details by ID, retrieve current authenticated user info
Workspace: Get workspace information; search across pages and databases with filtering and sorting options
Comments: List existing comments, create new comment discussions, reply to existing threads
Content Conversion: Convert between markdown and Notion blocks format (automatic in most tools)
Help: Get on-demand detailed documentation for any tool
Key Advantages:
Markdown-first for human readability and AI processing
Composite operations replacing multiple API requests
Auto-pagination without manual cursor management
Native batch operation support
~77% token reduction through tiered descriptions and on-demand documentation
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"?
9 composite tools that consolidate Notion's 28+ REST API endpoints into action-based 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 |
Operations | Composite actions (1 call) | Atomic (2+ calls) |
Pagination | Auto-pagination | Manual cursor |
Bulk Operations | Native batch support | Loop manually |
Tools | 9 tools (39 actions) | 28+ endpoint tools |
Token Efficiency | Optimized | Standard |
Quick Start
Remote Mode (OAuth) -- No token needed
Connect directly via URL with OAuth authentication. Your MCP client handles the OAuth flow automatically — just authorize with your Notion account when prompted.
{
"mcpServers": {
"better-notion": {
"type": "http",
"url": "https://better-notion-mcp.n24q02m.com/mcp"
}
}
}Supported by Claude Desktop, Claude Code, Cursor, VS Code Copilot, and other clients with OAuth support.
Local Mode (Token)
Get your token: https://www.notion.so/my-integrations -> Create integration -> Copy token -> Share pages
Option 1: Package Manager (Recommended)
{
"mcpServers": {
"better-notion": {
"command": "bun",
"args": ["x", "@n24q02m/better-notion-mcp@latest"],
"env": {
"NOTION_TOKEN": "ntn_..." // required: Notion integration token
}
}
}
}Alternatively, you can use npx, pnpm dlx, or yarn dlx:
Runner |
|
|
npx |
|
|
pnpm |
|
|
yarn |
|
|
Option 2: Docker
{
"mcpServers": {
"better-notion": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"--name", "mcp-notion",
"-e", "NOTION_TOKEN", // required: pass-through from env below
"n24q02m/better-notion-mcp:latest"
],
"env": {
"NOTION_TOKEN": "ntn_..." // required: Notion integration token
}
}
}
}Self-Hosting (Remote Mode)
You can self-host the remote server with your own Notion OAuth app.
Prerequisites:
Create a Public Integration at https://www.notion.so/my-integrations
Set the redirect URI to
https://your-domain.com/callbackNote your
client_idandclient_secret
docker run -p 8080:8080 \
-e TRANSPORT_MODE=http \
-e PUBLIC_URL=https://your-domain.com \
-e NOTION_OAUTH_CLIENT_ID=your-client-id \
-e NOTION_OAUTH_CLIENT_SECRET=your-client-secret \
-e DCR_SERVER_SECRET=$(openssl rand -hex 32) \
n24q02m/better-notion-mcp:latestVariable | Description |
| Set to |
| Your server's public URL (used for OAuth redirects) |
| Notion Public Integration client ID |
| Notion Public Integration client secret |
| HMAC secret for stateless client registration |
| Server port (default: |
Tools
Tool | Actions |
| create, get, get_property, update, move, archive, restore, duplicate |
| create, get, query, create_page, update_page, delete_page, create_data_source, update_data_source, update_database, list_templates |
| get, children, append, update, delete |
| list, get, me, from_workspace |
| info, search |
| list, get, create |
| markdown-to-blocks, blocks-to-markdown |
| create, send, complete, retrieve, list |
| Get full documentation for any tool |
Token Optimization
~77% token reduction via tiered descriptions:
Tier | Purpose | When |
Tier 1 | Compressed descriptions | Always loaded |
Tier 2 | Full docs via | On-demand |
Tier 3 | MCP Resources | Supported clients |
{"name": "help", "tool_name": "pages"}MCP Resources (Tier 3)
Clients that support MCP Resources can load full tool documentation:
URI | Description |
| Pages tool docs |
| Databases tool docs |
| Blocks tool docs |
| Users tool docs |
| Workspace tool docs |
| Comments tool docs |
| Content Convert tool docs |
| File Uploads tool docs |
Build from Source
git clone https://github.com/n24q02m/better-notion-mcp
cd better-notion-mcp
mise run setup
bun run buildRequirements: Node.js 24+, bun
Compatible With
Also by n24q02m
Server | Description | Install |
Web search, content extraction, library docs |
| |
Persistent AI memory with hybrid search |
| |
Email (IMAP/SMTP) for AI agents |
| |
Godot Engine for AI agents |
|
Contributing
See CONTRIBUTING.md
License
MIT - See LICENSE