by n24q02m
Provides a markdown‑first Model Context Protocol server for Notion, consolidating dozens of REST endpoints into composite actions that are token‑efficient and ready for AI agents.
Better Notion MCP offers a server that translates Notion data into Markdown and bundles common operations into high‑level tools. It replaces the raw JSON‑centric official MCP with a more human‑readable, AI‑friendly interface, handling pagination, batch processing, and token optimisation automatically.
npx command (or Docker as an alternative).pages.create, databases.query, or content_convert.markdown-to-blocks.help tool to retrieve full documentation for any tool when needed.npx configuration{
"mcpServers": {
"better-notion": {
"command": "npx",
"args": ["-y", "@n24q02m/better-notion-mcp@latest"],
"env": { "NOTION_TOKEN": "<YOUR_NOTION_TOKEN>" }
}
}
}
help tool or notion://docs/* URIs.n24q02m/better-notion-mcp for containerised deployments.Q: Do I need Node.js installed?
A: Yes, Node.js 24+ is required when running via npx. Docker users only need Docker.
Q: Which environment variable holds the Notion token?
A: Set NOTION_TOKEN to the integration token (ntn_...).
Q: Can I use the server without Docker?
A: Absolutely. The recommended method is the npx command shown above.
Q: How do I get detailed tool documentation?
A: Call the help tool with the tool name or use the notion://docs/* URIs if the client supports MCP Resources.
Q: Is the project open source? A: Yes, it is released under the MIT license and the source is on GitHub.
Markdown-First MCP Server for Notion - Optimized for AI Agents
9 composite tools that consolidate Notion's 28+ REST API endpoints into action-based operations optimized for AI agents.
| 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 |
Get your token: https://www.notion.so/my-integrations → Create integration → Copy token → Share pages
{
"mcpServers": {
"better-notion": {
"command": "npx",
"args": ["-y", "@n24q02m/better-notion-mcp@latest"],
"env": {
"NOTION_TOKEN": "ntn_..." // required: Notion integration token
}
}
}
}
{
"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
}
}
}
}
| Tool | Actions |
|---|---|
pages |
create, get, get_property, update, move, archive, restore, duplicate |
databases |
create, get, query, create_page, update_page, delete_page, create_data_source, update_data_source, update_database, list_templates |
blocks |
get, children, append, update, delete |
users |
list, get, me, from_workspace |
workspace |
info, search |
comments |
list, get, create |
content_convert |
markdown-to-blocks, blocks-to-markdown |
file_uploads |
create, send, complete, retrieve, list |
help |
Get full documentation for any tool |
~77% token reduction via tiered descriptions:
| Tier | Purpose | When |
|---|---|---|
| Tier 1 | Compressed descriptions | Always loaded |
| Tier 2 | Full docs via help tool |
On-demand |
| Tier 3 | MCP Resources | Supported clients |
{"name": "help", "tool_name": "pages"}
Clients that support MCP Resources can load full tool documentation:
| URI | Description |
|---|---|
notion://docs/pages |
Pages tool docs |
notion://docs/databases |
Databases tool docs |
notion://docs/blocks |
Blocks tool docs |
notion://docs/users |
Users tool docs |
notion://docs/workspace |
Workspace tool docs |
notion://docs/comments |
Comments tool docs |
notion://docs/content_convert |
Content Convert tool docs |
notion://docs/file_uploads |
File Uploads tool docs |
git clone https://github.com/n24q02m/better-notion-mcp
cd better-notion-mcp
mise run setup
pnpm build
Requirements: Node.js 24+, pnpm
See CONTRIBUTING.md
MIT - See LICENSE
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
by zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
by modelcontextprotocol
Model Context Protocol Servers
by modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
by cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
by upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.
by continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.