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
helptool - 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
| 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 |
| 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 |
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).
| 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 |
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_idandclient_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 devMIT -- See LICENSE.