better-notion-mcp

Better Notion MCP

mcp-name: io.github.n24q02m/better-notion-mcp

Markdown-first Notion API server for AI agents -- 9 composite tools replacing 28+ endpoint calls

Features

• Markdown in, Markdown out -- human-readable content instead of raw JSON blocks
• 9 composite tools with 39 actions -- one call instead of chaining 2+ atomic endpoints
• Auto-pagination and bulk operations -- no manual cursor handling or looping
• Tiered token optimization -- ~77% reduction via compressed descriptions + on-demand help tool
• Dual transport -- local stdio (token) or remote HTTP (OAuth 2.1, no token needed)

Quick Start

Claude Code Plugin (Recommended)

Via marketplace (includes skills: /organize-database, /bulk-update):

/plugin marketplace add n24q02m/claude-plugins
/plugin install better-notion-mcp@n24q02m-plugins

Plugin uses remote OAuth — no NOTION_TOKEN needed. Browser opens for Notion authorization on first use.

Gemini CLI Extension

gemini extensions install https://github.com/n24q02m/better-notion-mcp

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.better-notion-mcp]
command = "npx"
args = ["-y", "@n24q02m/better-notion-mcp"]

MCP Server

Option 1: Remote (OAuth) -- No token needed

Connect directly via URL with OAuth authentication. Your MCP client handles the OAuth flow automatically.

{
  "mcpServers": {
    "better-notion": {
      "type": "http",
      "url": "https://better-notion-mcp.n24q02m.com/mcp"
    }
  }
}

Option 2: npx

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

Set NOTION_TOKEN in ~/.claude/settings.local.json or your shell profile:

export NOTION_TOKEN="ntn_..."

Then add to your MCP client config:

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

Other runners: bun x, pnpm dlx, yarn dlx also work.

Option 3: Docker

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

Tools

Tool	Actions	Description
pages	create, get, get_property, update, move, archive, restore, duplicate	Create, read, update, and organize pages
databases	create, get, query, create_page, update_page, delete_page, create_data_source, update_data_source, update_database, list_templates	Database CRUD and page management within databases
blocks	get, children, append, update, delete	Read and manipulate block content
users	list, get, me, from_workspace	List and retrieve user information
workspace	info, search	Workspace metadata and cross-workspace search
comments	list, get, create	Page and block comments
content_convert	markdown-to-blocks, blocks-to-markdown	Convert between Markdown and Notion blocks
file_uploads	create, send, complete, retrieve, list	Upload files to Notion
help	-	Get full documentation for any tool

MCP Resources