About io.github.n24q02m/better-notion-mcp
io.github.n24q02m/better-notion-mcp is an MCP server in the Commerce category: markdown-first MCP server for Notion API with 9 composite tools and 39+ actions.
Install
claude mcp add io-github-n24q02m-better-notion-mcp -- npx -y @n24q02m/better-notion-mcpnpx -y @n24q02m/better-notion-mcpThis server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.
Tools (11)
blocks`get`, `children`, `append`, `update`, `delete`
Parameters not published.
comments`list`, `get`, `create`
Parameters not published.
config`status`, `setup_status`, `setup_start`, `setup_reset`, `setup_complete`, `set`, `cache_clear`
Parameters not published.
config__open_relay-
Parameters not published.
content_convert`markdown-to-blocks`, `blocks-to-markdown`
Parameters not published.
databases`create`, `get`, `query`, `create_page`, `update_page`, `delete_page`, `create_data_source`, `update_data_source`, `update_database`, `list_templates`
Parameters not published.
file_uploads`create`, `send`, `complete`, `retrieve`, `list`
Parameters not published.
help-
Parameters not published.
pages`create`, `get`, `get_property`, `update`, `move`, `archive`, `restore`, `duplicate`
Parameters not published.
users`list`, `get`, `me`, `from_workspace`
Parameters not published.
workspace`info`, `search`
Parameters not published.
Ask AI
Ask AI about io.github.n24q02m/better-notion-mcp
Powered by Claude · Grounded in docs
Security checks
- ✓README presentThe repository ships documentation.
5 checks have not been run yet.
README
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
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
helptool - 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:
- 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_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
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.
README copy captured when this server was indexed; it may lag the repository. The original is authoritative.