Better Notion Mcp
About
Markdown-First MCP Server for Notion - Composite Actions, Auto-Pagination, Bulk Operations optimized for AI Agents
Details
- Author
- n24q02m
- Downloads
- 400
- Categories
- Productivity, Other, Knowledge Base, Automation, AI
Jump to
- 7 mega action-based tools covering 30+ actions
- Markdown content format (human-readable, token-efficient)
- Composite actions (create page + content + properties in one call)
- Transparent auto-pagination for large datasets
- Native bulk operations for multiple items
- Smart search that auto-detects best match in database queries
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Better Notion McpCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install via npx or Docker. Set the NOTION_TOKEN environment variable with your Notion integration token. Configure the server in your MCP client (e.g., Claude Desktop) using the provided JSON snippet. No additional dependencies are required for usage.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"better notion mcp": {
"better-notion": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"NOTION_TOKEN",
"n24q02m/better-notion-mcp:latest"
],
"env": {
"NOTION_TOKEN": "your_token_here"
}
}
}
}
}McpServers
{
"better-notion": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"NOTION_TOKEN",
"n24q02m/better-notion-mcp:latest"
],
"env": {
"NOTION_TOKEN": "your_token_here"
}
}
}mcp-name: io.github.n24q02m/better-notion-mcp
Markdown-first Notion for AI agents -- pages, databases, blocks, and comments in one call.
- Features
- Install
- CLI
- Remote (HTTP mode)
- Smithery
- Status
- Documentation
- Tools
- Configuration
- Deploy to Cloudflare
- Comparison
- Security
- Build from Source
- Trust Model
- License
- Markdown in, Markdown out-- human-readable content instead of raw JSON blocks
- 8 composite tools, 39 actions-- one call instead of chaining 2+ atomic Notion endpoints (plusconfig,help, and a relay-setup tool)
- Auto-pagination and bulk operations-- no manual cursor handling or looping
- Tiered token optimization-- ~77% reduction via compressed descriptions + on-demandhelptool
- Dual transport-- local stdio (integration token) or remote HTTP (OAuth 2.1, no token to paste)
Run withnpx(Node.js >= 24) and a Notion integration token fromhttps://www.notion.so/my-integrations(starts withntn_):
// MCP client config (e.g. .mcp.json / Claude Code / Cursor) { "mcpServers": { "better-notion-mcp": { "command": "npx", "args": ["--yes", "@n24q02m/better-notion-mcp@latest"], "env": { "NOTION_TOKEN": "ntn_your_token_here" } } } }
Or run the published Docker image (stdio):
docker run --rm -i -e NOTION_TOKEN=ntn_your_token_here n24q02m/better-notion-mcp:latest
Installing the package exposes abetter-notion-mcpbinary (run it withnpxor after a global install). It hasno subcommands-- running it starts the MCP server and speaks the protocol over stdin/stdout, so it is normally launched by an MCP client rather than by hand.
# Start the stdio server (default transport; requires NOTION_TOKEN) NOTION_TOKEN=ntn_your_token_here npx --yes @n24q02m/better-notion-mcp@latest # Start the remote HTTP server (OAuth 2.1) instead of stdio npx --yes @n24q02m/better-notion-mcp@latest --http
SeeConfigurationfor the full environment-variable reference.
Deployed with the HTTP transport, the server is a remote endpoint gated by OAuth 2.1 -- no integration token to paste. Point an MCP client that supports remote HTTP servers at the host you deployed it on:
// MCP client config -- remote HTTP (OAuth 2.1) { "mcpServers": { "better-notion-mcp": { "type": "http", "url": "https://<your-host>/mcp" } } }
On first connect the client opens Notion's OAuth consent screen; per-user access tokens are held in-process only (seeTrust Model). To stand up such an instance, seeSelf-Hosting (Remote Mode)andDeploy to Cloudflare.
The repo ships asmithery.yamlconfig forSmithery. Smithery launches the server over stdio (npx -y @n24q02m/better-notion-mcp) and requires no install-time config -- provide your Notion credentials at runtime through the server's own setup flow (NOTION_TOKENenv, or the relay form; seeConfiguration).
2026-05-02 -- Architecture stabilization update
Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins.The architecture is now stable: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.
Apologies for the instability period. If you encountered issues with prior versions, please update to the latest release and follow the currentSetup guide-- most prior workarounds are no longer needed.
- wet-mcp-- Web search + content extraction
- mnemo-mcp-- Persistent AI memory
- imagine-mcp-- Image/video understanding + generation
- better-email-mcp-- Email management
- better-telegram-mcp-- Telegram
- better-godot-mcp-- Godot Engine
- better-code-review-graph-- Code review knowledge graph
All plugins share the same architecture -- install once, learn pattern transfers.
Full docs atmcp.n24q02m.com/servers/better-notion-mcp/:
- Setup-- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
- Modes overview-- stdio (local, integration token) and HTTP (remote, OAuth 2.1)
- Multi-user setup-- per-JWT-sub credential model (HTTP mode)
Install with AI agent-- paste this to your AI coding agent:
Install MCP serverbetter-notion-mcpfollowing the steps athttps://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-notion-mcp/setup-with-agent.md
Eight composite Notion tools (39 actions) plus three infrastructure tools (config,config__open_relay,help):
You can self-host the remote server with your own Notion OAuth app.
- Create aPublic Integrationathttps://www.notion.so/my-integrations
- Set the redirect URI tohttps://your-domain.com/callback
- Note yourclient_idandclient_secret
docker run -p 8080:8080 \ -e TRANSPORT_MODE=http \ -e PORT=8080 \ -e PUBLIC_URL=https://your-domain.com \ -e NOTION_OAUTH_CLIENT_ID=your-client-id \ -e NOTION_OAUTH_CLIENT_SECRET=your-client-secret \ n24q02m/better-notion-mcp:latest
Run your own multi-user better-notion-mcp serverless on Cloudflare (Worker + Container + KV).
Prerequisites:a Cloudflare account on theWorkers Paid plan— required for Containers (the Cloudflare free tier does not include Containers) — and thewranglerCLI.
- git clone https://github.com/n24q02m/better-notion-mcp && cd better-notion-mcp
- wrangler login
- Provision the KV namespace and paste its id intowrangler.jsonc:
wrangler kv namespace create better-notion-kv
wrangler secret put CREDENTIAL_SECRET wrangler secret put NOTION_OAUTH_CLIENT_ID wrangler secret put NOTION_OAUTH_CLIENT_SECRET
wrangler containers push better-notion-mcp:beta wrangler deploy
Per-user Notion access tokens are encrypted into KV (MCP_STORAGE_BACKEND=cf-kv), so they survive scale-to-zero. Do NOT setMCP_AUTH_DISABLEon a shared/public deployment — it collapses all users into a single token bucket.
How better-notion-mcp stacks up against direct competitors in each pillar:
- 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
This plugin implementsTC-NearZK(in-memory, ephemeral). Seethe trust model referencefor full classification.
Official Notion MCP server for searching, reading, creating, and updating Notion pages, databases, and workspace content from AI agents.
Official MCP server for the Notion API, enabling real-time interactions via Server-Sent Events (SSE).
An MCP server for the Notion API, allowing language models to interact with Notion workspaces.
Connects AI assistants to your Notion workspace to search and manage pages, databases, and content.
Connects AI assistants to your Notion workspace, allowing you to search, create, and manage content using natural language.
Search, read, create, and update pages and databases in your Notion workspace.
Integrate with Notion workspaces to manage databases, pages, and content.
An MCP server for interacting with your Notion workspace, enabling LLMs to manage pages and databases.
An optimized, read-only MCP server for the Notion API with asynchronous processing.
MCP server for Paperless-ngx document management. 43 tools for AI-powered document organization - full CRUD on documents, tags, correspondents, document types, storage paths, and custom fields.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
