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

Get your token: https://www.notion.so/my-integrations → Create integration → Copy token → Share pages

Option 1: npx (Recommended)

{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": ["-y", "@n24q02m/better-notion-mcp@latest"],
      "env": {
        "NOTION_TOKEN": "ntn_..."                  // required: Notion integration token
      }
    }
  }
}

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
      }
    }
  }
}

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 |

{"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

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