Better Notion MCP

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

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

• Markdown in, Markdown out -- human-readable content instead of raw JSON blocks
• 10 composite tools with 44 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)

With AI Agent -- copy and send this to your AI agent:

Please set up @n24q02m/better-notion-mcp for me. Follow this guide: https://raw.githubusercontent.com/n24q02m/better-notion-mcp/main/docs/setup-with-agent.md

Manual Setup -- follow docs/setup-manual.md

No environment variables needed. On first start, the server opens a setup page in your browser:

1. Start the server (via plugin, npx, or Docker)
2. A setup URL appears -- open it in any browser
3. Fill in your credentials on the guided form
4. Credentials are encrypted and stored locally

Your credentials never leave your machine. The relay server only sees encrypted data.

For CI/automation, you can still use environment variables (see below).

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

• 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)

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

MIT -- See LICENSE.