Better Notion MCP

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

Markdown-first Notion for AI agents -- pages, databases, blocks, and comments in one call.

<!-- Badge Row 1: Status -->

<!-- Badge Row 2: Tech -->

<!-- BEGIN: AUTO-GENERATED-CROSS-PROMO --> <details> <summary><strong>Sister projects from n24q02m</strong> (click to expand)</summary>

</details> <!-- END: AUTO-GENERATED-CROSS-PROMO -->

Table of contents

• Features
• Install
• Status
• Documentation
• Tools
• Configuration
• Deploy to Cloudflare
• Comparison
• Security
• Build from Source
• Trust Model
• License

<a href="https://glama.ai/mcp/servers/n24q02m/better-notion-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/n24q02m/better-notion-mcp/badge" alt="Better Notion MCP server" /> </a>

Features

• Markdown in, Markdown out -- human-readable content instead of raw JSON blocks
• 8 composite tools, 39 actions -- one call instead of chaining 2+ atomic Notion endpoints (plus config, help, and a relay-setup tool)
• 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 (integration token) or remote HTTP (OAuth 2.1, no token to paste)

Install

Run with npx (Node.js >= 24) and a Notion integration token from <https://www.notion.so/my-integrations> (starts with ntn_):

// MCP client config (e.g. .mcp.json / Claude Code / Cursor)
{
  "mcpServers": {
    "better-notion-mcp": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/better-notion-mcp@latest"],
      "env": { "NOTION_TOKEN": "ntn_your_token_here" }
    }
  }
}

Or run the published Docker image (stdio):

docker run --rm -i -e NOTION_TOKEN=ntn_your_token_here n24q02m/better-notion-mcp:latest

See the Documentation section for per-client setup (Claude Code, Codex, Gemini CLI, Cursor, Windsurf) and HTTP/OAuth mode.

Status

2026-05-02 -- Architecture stabilization update

>

Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins. The architecture is now stable: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.

>

Apologies for the instability period. If you encountered issues with prior versions, please update to the latest release and follow the current Setup guide -- most prior workarounds are no longer needed.

>

Related plugins from the same author: - wet-mcp -- Web search + content extraction - mnemo-mcp -- Persistent AI memory - imagine-mcp -- Image/video understanding + generation - better-email-mcp -- Email management - better-telegram-mcp -- Telegram - better-godot-mcp -- Godot Engine - better-code-review-graph -- Code review knowledge graph

>

All plugins share the same architecture -- install once, learn pattern transfers.

Documentation

Full docs at [mcp.n24q02m.com/servers/better-notion-mcp/](https://mcp.n24q02m.com/servers/better-notion-mcp/):

• Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
• Modes overview -- stdio (local, integration token) and HTTP (remote, OAuth 2.1)
• Multi-user setup -- per-JWT-sub credential model (HTTP mode)

Install with AI agent -- paste this to your AI coding agent:

Install MCP server better-notion-mcp following the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-notion-mcp/setup-with-agent.md

Tools

Eight composite Notion tools (39 actions) plus three infrastructure tools (config, config__open_relay, help):

MCP Resources

Configuration

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 PORT=8080 \
  -e PUBLIC_URL=https://your-domain.com \
  -e NOTION_OAUTH_CLIENT_ID=your-client-id \
  -e NOTION_OAUTH_CLIENT_SECRET=your-client-secret \
  n24q02m/better-notion-mcp:latest

Deploy to Cloudflare

Run your own multi-user better-notion-mcp serverless on Cloudflare (Worker + Container + KV).

Prerequisites: a Cloudflare account on the Workers Paid plan and the wrangler CLI.

1. git clone https://github.com/n24q02m/better-notion-mcp && cd better-notion-mcp
2. wrangler login
3. Provision the KV namespace and paste its id into wrangler.jsonc:

   wrangler kv namespace create better-notion-kv

1. Set secrets:

   wrangler secret put CREDENTIAL_SECRET
   wrangler secret put NOTION_OAUTH_CLIENT_ID
   wrangler secret put NOTION_OAUTH_CLIENT_SECRET

CREDENTIAL_SECRET is REQUIRED: it derives a deterministic OAuth signing key so user identity survives container recreation.

1. Push the http image to the CF managed registry and deploy:

   wrangler containers push better-notion-mcp:beta
   wrangler deploy

1. Complete the Notion OAuth flow in the browser at your Worker domain.

Per-user Notion access tokens are encrypted into KV (MCP_STORAGE_BACKEND=cf-kv), so they survive scale-to-zero. Do NOT set MCP_AUTH_DISABLE on a shared/public deployment — it collapses all users into a single token bucket.

Comparison

How better-notion-mcp stacks up against direct competitors in each pillar:

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

Trust Model

This plugin implements TC-NearZK (in-memory, ephemeral). See the trust model reference for full classification.

License

MIT -- See LICENSE.