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

| Feature | Better Notion MCP | Official Notion MCP | | --------------------- | ---------------------------------------------------------------------- | ---------------------------------------------- | | Content Format | Markdown (human-readable) | Raw JSON blocks (verbose) | | Operations | Composite actions (create page + content + properties in 1 call) | Atomic operations (2+ separate calls required) | | Pagination | Auto-pagination (transparent) | Manual cursor management | | Bulk Operations | Native batch support (create/update/delete multiple items at once) | Loop through items manually | | Tool Architecture | 7 mega action-based tools (30+ actions) | 28+ individual endpoint tools | | Database Query | Smart search (auto-detect best match) | Manual filters + sorts required | | Token Efficiency | Optimized for AI context | Standard API responses | | Setup | Simple (NOTION_TOKEN only) | OAuth flow or token |

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

Limitations

Supported Block Types (Markdown Conversion):

✅ Headings (H1-H3), Paragraphs, Lists (bulleted/numbered)
✅ Code blocks, Quotes, Dividers
✅ Inline formatting (bold, italic, code, strikethrough, links)

Unsupported Block Types:

❌ Tables, Toggles, Callouts, Columns
❌ Databases, Embeds, Images, Files
❌ Synced blocks, Templates

Build from Source

This project uses mise for tool version management. If you don't have mise installed, see mise.jdx.dev.

git clone https://github.com/n24q02m/better-notion-mcp
cd better-notion-mcp

mise trust
mise install

pnpm install
pnpm build

uv venv
uv pip install pre-commit
uv run pre-commit install
uv run pre-commit run --all-file

Prerequisites: mise or Node.js 22+ and pnpm.

Available Commands

pnpm dev                    # Run development server with auto-reload
pnpm build                  # Build the project
pnpm test                   # Run tests
pnpm test:watch             # Run tests in watch mode
pnpm test:coverage          # Run tests with coverage report
pnpm check                  # Check formatting, linting & types (Biome + TypeScript)
pnpm check:fix              # Auto-fix formatting and linting issues

Contributing

Contributions welcome! See CONTRIBUTING.md for:

Development workflow (verified via CI)
Commit convention (enforced via git hooks)
Testing and code quality standards

License

MIT License - See LICENSE

Star this repo if you find it useful! ⭐

MCP Servers