n24q02m/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

CI codecov npm Docker License: MIT

TypeScript Node.js Notion semantic-release Renovate

Features

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

Setup

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

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
setup	status, start, reset, complete	Credential setup via browser relay, status check, reset, re-resolve
help	-	Get full documentation for any tool

MCP Resources

URI	Description
notion://docs/pages	Page operations reference
notion://docs/databases	Database operations reference
notion://docs/blocks	Block operations reference
notion://docs/users	User operations reference
notion://docs/workspace	Workspace operations reference
notion://docs/comments	Comment operations reference
notion://docs/content_convert	Content conversion reference
notion://docs/file_uploads	File upload reference

Zero-Config Setup

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

Configuration

Variable	Required	Default	Description
NOTION_TOKEN	Yes (stdio)	-	Notion integration token
TRANSPORT_MODE	No	stdio	Set to http for remote mode
PUBLIC_URL	Yes (http)	-	Server's public URL for OAuth redirects
NOTION_OAUTH_CLIENT_ID	Yes (http)	-	Notion Public Integration client ID
NOTION_OAUTH_CLIENT_SECRET	Yes (http)	-	Notion Public Integration client secret
DCR_SERVER_SECRET	Yes (http)	-	HMAC secret for stateless client registration
PORT	No	8080	Server port

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

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

License

MIT -- See LICENSE.