io.github.n24q02m/better-notion-mcp

Name: io.github.n24q02m/better-notion-mcp
Rating: 1.1 (21 reviews)
Author: n24q02m

平台与服务

by n24q02m

面向 Notion API 的 Markdown-first MCP server，内置 9 个复合工具和 39+ actions，适合文档自动化。

21GitHub

什么是 io.github.n24q02m/better-notion-mcp？

面向 Notion API 的 Markdown-first MCP server，内置 9 个复合工具和 39+ actions，适合文档自动化。

README

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)

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
`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:

Start the server (via plugin, npx, or Docker)
A setup URL appears -- open it in any browser
Fill in your credentials on the guided form
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:

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

bash

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

bash

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

License

MIT -- See LICENSE.

常见问题