Better Notion MCP

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

Why "Better"?

7 mega action-based tools that consolidate Notion's 28+ REST API endpoints into composite operations optimized for AI agents.

vs. Official Notion MCP Server

Installation

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

Quick Start

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 Overview

7 mega tools with 30+ actions:

• Composite Actions: Combine operations (e.g., create page + content + properties in 1 call)
• Auto-Pagination: Transparent handling of large datasets
• Bulk Operations: Process multiple items efficiently
• Smart Search: Auto-detect best matches in database queries

Development

Build from Source

git clone https://github.com/n24q02m/better-notion-mcp
cd better-notion-mcp
mise trust && mise install  # Install Node.js 22 + pnpm via mise
pnpm build                  # Build the project

Prerequisites: mise for managing Node.js and pnpm versions.

Available Commands

pnpm run dev
pnpm run build
pnpm run test
pnpm run test:watch
pnpm run test:coverage
pnpm run lint
pnpm run format:check
pnpm run type-check
pnpm run check
pnpm run changeset

Contributing

Contributions welcome! See CONTRIBUTING.md for:

• Development workflow with changesets
• Commit convention (enforced via git hooks)
• Testing and code quality standards

License

MIT License - See LICENSE

Star this repo if you find it useful! ⭐