ARCHIVED 2026-09-13 — This repository is no longer maintained. Use the official Notion API instead of this MCP server. Existing installations keep working but receive no updates or support.
Better Notion MCP
mcp-name: io.github.n24q02m/better-notion-mcp
Markdown-first Notion for AI agents -- pages, databases, blocks, and comments in one call.
Sister projects from n24q02m (click to expand)
| Project | Tagline | Tag |
|---|
| agent-chat-plugin | Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling |
| better-code-review-graph | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |
| better-drive | 2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling |
| better-email-mcp | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |
| better-godot-mcp | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |
| better-notion-mcp | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |
| better-semantic-release | Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling |
| better-telegram-mcp | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |
| better-workspace-mcp | Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP |
| claude-plugins | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |
| imagine-mcp | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |
| jules-task-archiver | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |
| mcp-core | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |
| mnemo-mcp | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |
| qwen3-embed | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |
| skret | Secrets without the server. | CLI |
| tacet | A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling |
| web-core | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |
| wet-mcp | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |
Table of contents
Features
- 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 (plus
config, 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-demand
help tool
- Dual transport -- local stdio (integration token) or remote HTTP (OAuth 2.1, no token to paste)
Install
Run with npx (Node.js >= 24) and a Notion integration token from https://www.notion.so/my-integrations (starts with ntn_):
{
"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
Install matrix
| Client | Install |
|---|
| Claude Code | /plugin marketplace add n24q02m/claude-plugins + /plugin install better-notion-mcp@n24q02m-plugins (stdio; prompts for NOTION_TOKEN), or an mcpServers entry in .mcp.json / client settings |
| Codex CLI | [mcp_servers.better-notion-mcp] block in ~/.codex/config.toml (stdio command/args or HTTP type/url) |
| OpenCode | mcpServers block in opencode.json |
| Cursor / Windsurf / Gemini CLI / any MCP client | mcpServers JSON in the client's config — same shape as the example above |
Full per-client walkthroughs: mcp.n24q02m.com/servers/better-notion-mcp/setup/.
See the Documentation section for per-client setup (Claude Code, Codex, Gemini CLI, Cursor, Windsurf) and HTTP/OAuth mode.
CLI
Installing the package exposes a better-notion-mcp binary (run it with npx or after a global install). It has no 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.
NOTION_TOKEN=ntn_your_token_here npx --yes @n24q02m/better-notion-mcp@latest
npx --yes @n24q02m/better-notion-mcp@latest --http
| Argument / env | Effect |
|---|
| (none) | stdio transport (default); requires NOTION_TOKEN |
--http | HTTP transport with OAuth 2.1 (equivalent to TRANSPORT_MODE=http / MCP_TRANSPORT=http) |
See Configuration for the full environment-variable reference.
Remote (HTTP mode)
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:
{
"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 (see Trust Model). To stand up such an instance, see Self-Hosting (Remote Mode) and Deploy to Cloudflare.
Smithery
The repo ships a smithery.yaml config for Smithery. 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_TOKEN env, or the relay form; see Configuration).
Status
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 current Setup guide -- most prior workarounds are no longer needed.
Related plugins from the same author:
All plugins share the same architecture -- install once, learn pattern transfers.
Documentation
Full docs at mcp.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 server better-notion-mcp following the steps at
https://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):
| 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 comments and discussion replies |
content_convert | markdown-to-blocks, blocks-to-markdown | Convert between Markdown and Notion blocks (uses a direction parameter) |
file_uploads | create, send, complete, retrieve, list | Upload files to Notion (single or multi-part) |
config | status, setup_status, setup_start, setup_reset, setup_complete, set, cache_clear | Inspect and manage credential state and configuration lifecycle |
config__open_relay | - | Open the relay configuration form in the browser and return the relay URL + credential state |
help | - | Get full documentation for any composite tool (tool_name parameter) |
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 |
Configuration
| Variable | Required | Default | Description |
|---|
NOTION_TOKEN | Yes (stdio) | - | Notion integration token |
TRANSPORT_MODE / MCP_TRANSPORT | No | stdio | Set either to http for remote mode (or pass --http) |
PUBLIC_URL | No (http) | - | Server's public URL for OAuth redirect links |
NOTION_OAUTH_CLIENT_ID | Yes (http) | - | Notion Public Integration client ID (or --oauth-client-id=<id> CLI flag, which overrides the env var) |
NOTION_OAUTH_CLIENT_SECRET | Yes (http) | - | Notion Public Integration client secret (or --oauth-client-secret=<secret> CLI flag, which overrides the env var) |
MCP_AUTH_DISABLE | No (http) | - | Set to 1 to skip Bearer JWT verification when behind an external auth gateway |
PORT | No | 0 (OS-assigned) | Server port; set explicitly (e.g. 8080) to bind a fixed port |
HOST | No | - | Bind address (http mode) |
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
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
Deploy to Cloudflare
Run your own multi-user better-notion-mcp serverless on Cloudflare (Worker + Container + KV).
Deployment (CD-managed)
Managed deployments go through CI, never by hand: the deploy-cf job in
.github/workflows/cd.yml runs after a release,
checks out the released tag, builds the immutable http-slim image at the
released version, pushes it to the Cloudflare managed registry, deploys, and
gates on a canary check — a managed instance can therefore only ever run an
exact release tag. Manual wrangler deploy against a managed/operated
instance is not permitted: it breaks the release-tag ↔ live-image
correspondence, and the next CD run would overwrite it.
The job is gated by the CF_HOSTED_ENABLED repository Actions variable —
currently false, so releases do not publish a hosted endpoint. To run your
own instance, use the self-host steps below.
Prerequisites: a Cloudflare account on the Workers Paid plan — required for Containers (the Cloudflare free tier does not include Containers) — and the wrangler CLI.
git clone https://github.com/n24q02m/better-notion-mcp && cd better-notion-mcpwrangler login- Provision the KV namespace and paste its id into
wrangler.jsonc:
wrangler kv namespace create better-notion-kv
- Set secrets:
wrangler secret put CREDENTIAL_SECRET
wrangler secret put NOTION_OAUTH_CLIENT_ID
wrangler secret put NOTION_OAUTH_CLIENT_SECRET
CREDENTIAL_SECRET is REQUIRED: it derives a deterministic OAuth signing key so
user identity survives container recreation.
- Push the http image to the CF managed registry and deploy:
wrangler containers push better-notion-mcp:beta
wrangler deploy
- Complete the Notion OAuth flow in the browser at your Worker domain.
Per-user Notion access tokens are encrypted into KV (MCP_STORAGE_BACKEND=cf-kv),
so they survive scale-to-zero. Do NOT set MCP_AUTH_DISABLE on a shared/public
deployment — it collapses all users into a single token bucket.
Comparison
How better-notion-mcp stacks up against direct competitors in each pillar:
| Capability | better-notion-mcp | makenotion/notion-mcp-server | suekou/mcp-notion-server | awkoy/notion-mcp-server |
|---|
| Markdown in / out | Yes (round-trip on pages + blocks) | No (raw Notion JSON) | partial (experimental, append + opt-in convert) | Yes (round-trip + GFM) |
| Composite tool design | Yes (8 composite tools, 39 actions) | No (22 endpoint-mapped tools) | partial (simplified + raw JSON tools) | Yes (2 dispatch tools, 35+ ops) |
| File uploads to Notion | Yes (file_uploads, single + multi-part) | No | No | Yes (upload_file, single + multi-part) |
| Comments | Yes (comments: list/get/create) | Yes | Yes | Yes |
| Remote HTTP + OAuth 2.1 transport | Yes (per-JWT-sub multi-user) | partial (HTTP + bearer token, no OAuth) | No (stdio token only) | No (stdio token only) |
| Self-hostable | Yes (Docker, own OAuth app) | Yes | Yes | Yes |
| License | Apache-2.0 | ? | MIT | MIT |
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
Trust Model
This plugin implements TC-NearZK (in-memory, ephemeral). See the trust model reference for full classification.
| Mode | Storage | Encryption | Who can read your data? |
|---|
| HTTP n24q02m-hosted (default) | In-memory Map<sub, OAuthToken> | In-process only | Server process (cleared on restart) |
| HTTP self-host | Same as hosted | Same | Only you (admin = user) |
| stdio (local) | config.enc in the OS config dir (%APPDATA%\mcp\Config\config.enc on Windows, ~/.config/mcp/config.enc on Linux/macOS) | AES-GCM, machine-bound key | Only your OS user |
License
Apache-2.0 -- See LICENSE.