Better Notion MCP

Markdown-First MCP Server for Notion - Optimized for AI Agents

Why "Better"?

8 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 | 8 tools (30+ 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

NPX (Recommended)

{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": ["-y", "@n24q02m/better-notion-mcp@latest"],
      "env": {
        "NOTION_TOKEN": "your_token_here"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "better-notion": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "NOTION_TOKEN", "n24q02m/better-notion-mcp:latest"],
      "env": {
        "NOTION_TOKEN": "your_token_here"
      }
    }
  }
}

Tools

| Tool | Actions | |------|---------| | pages | create, get, update, archive, restore, duplicate | | databases | create, get, query, create_page, update_page, delete_page, create_data_source, update_data_source, update_database | | blocks | get, children, append, update, delete | | users | list, get, me, from_workspace | | workspace | info, search | | comments | list, create | | content_convert | markdown-to-blocks, blocks-to-markdown | | 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 |

{"name": "help", "tool_name": "pages"}

Limitations

Supported Blocks:

✅ Headings, Paragraphs, Lists, Code blocks, Quotes, Dividers
✅ Inline: bold, italic, code, strikethrough, links

Unsupported Blocks:

❌ Tables, Toggles, Callouts, Columns, Databases, Embeds, Images, Files

Build from Source

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

License

MIT - See LICENSE

MCP Servers