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@claude-plugins

Or install this plugin only:

/plugin marketplace add n24q02m/better-notion-mcp
/plugin install better-notion-mcp

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

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.

// Cursor (~/.cursor/mcp.json), Windsurf, Cline, Amp, OpenCode
{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": ["-y", "@n24q02m/better-notion-mcp@latest"]
    }
  }
}

# Codex (~/.codex/config.toml)
[mcp_servers.better-notion]
command = "npx"
args = ["-y", "@n24q02m/better-notion-mcp@latest"]

Option 3: Docker

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

Self-Hosting (Remote Mode)

You can self-host the remote server with your own Notion OAuth app.

Prerequisites:

1. Create a Public Integration at https://www.notion.so/my-integrations
2. Set the redirect URI to https://your-domain.com/callback
3. Note your client_id and client_secret

docker run -p 8080:8080 \
  -e TRANSPORT_MODE=http \
  -e PUBLIC_URL=https://your-domain.com \
  -e NOTION_OAUTH_CLIENT_ID=your-client-id \
  -e NOTION_OAUTH_CLIENT_SECRET=your-client-secret \
  -e DCR_SERVER_SECRET=$(openssl rand -hex 32) \
  n24q02m/better-notion-mcp:latest

Tools

MCP Resources

Configuration

Security

• OAuth 2.1 + PKCE S256 -- Secure authorization with code challenge
• Rate limiting -- 120 req/min/IP on HTTP transport
• Session owner binding -- IP check + TTL for pending token binds
• Null safety -- Handles Notion API quirks (comments.list 404, undefined rich_text)

Build from Source

git clone https://github.com/n24q02m/better-notion-mcp.git
cd better-notion-mcp
bun install
bun run dev

Compatible With

Also by n24q02m

Contributing

See CONTRIBUTING.md.

License

MIT -- See LICENSE.