# Better Notion MCP
**Markdown-First MCP Server for Notion - Optimized for AI Agents**
[](https://github.com/n24q02m/better-notion-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@n24q02m/better-notion-mcp)
[](https://hub.docker.com/r/n24q02m/better-notion-mcp)
[](LICENSE)
## 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
Get your token: <https://www.notion.so/my-integrations> → Create integration → Copy token → Share pages
### Option 1: npx (Recommended)
```jsonc
{
"mcpServers": {
"better-notion": {
"command": "npx",
"args": ["-y", "@n24q02m/better-notion-mcp@latest"],
"env": {
"NOTION_TOKEN": "ntn_..." // required: Notion integration token
}
}
}
}
```
### Option 2: Docker
```jsonc
{
"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
}
}
}
}
```
---
## Tools
| 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 |
---
## Token Optimization
**~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 |
```json
{"name": "help", "tool_name": "pages"}
```
### MCP Resources (Tier 3)
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 |
---
## Build from Source
```bash
git clone https://github.com/n24q02m/better-notion-mcp
cd better-notion-mcp
mise run setup
pnpm build
```
**Requirements:** Node.js 24+, pnpm
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
MIT - See [LICENSE](LICENSE)
