[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_119":120},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module '@n24q02m/better-notion-mcp' is not configured","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":26,"_34":-5,"_35":36,"_37":-5,"_38":-5,"_39":40,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":48,"_56":57,"_58":59,"_60":-5,"_61":-5,"_62":-5,"_63":-5,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":-5,"_75":-5,"_76":-5,"_77":48,"_78":-5,"_79":80,"_81":82,"_83":84,"_85":86,"_87":88,"_89":90,"_91":92},"apiUrl","https://odel.app/api","creator","n24q02m","moduleId","better-notion-mcp","@n24q02m/better-notion-mcp","displayName","better notion mcp","tagline","Markdown-first MCP server for Notion API with 9 composite tools and 39+ actions.","iconKey","https://avatars.githubusercontent.com/u/135627235?v=4","category","dev-tools","status","published","metaDescription","metaKeywords","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://better-notion-mcp.n24q02m.com/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1781363504000,"updatedAt",1781499757000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.n24q02m%2Fbetter-notion-mcp","sourceVerified",true,"importedAt","upstreamStars",31,"upstreamUpdatedAt",1781488710000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/n24q02m/better-notion-mcp","githubRepoFullName","n24q02m/better-notion-mcp","releaseId","ext-n24q02m-better-notion-mcp","version","2.34.7","descriptionMarkdown","# Better Notion MCP\n\nmcp-name: io.github.n24q02m/better-notion-mcp\n\n**Markdown-first Notion for AI agents -- pages, databases, blocks, and comments in one call.**\n\n\n[![CI](https://github.com/n24q02m/better-notion-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/n24q02m/better-notion-mcp/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/n24q02m/better-notion-mcp/graph/badge.svg?token=D7FSDVVTAN)](https://codecov.io/gh/n24q02m/better-notion-mcp)\n[![npm](https://img.shields.io/npm/v/@n24q02m/better-notion-mcp?logo=npm&logoColor=white)](https://www.npmjs.com/package/@n24q02m/better-notion-mcp)\n[![Docker](https://img.shields.io/docker/v/n24q02m/better-notion-mcp?label=docker&logo=docker&logoColor=white&sort=semver)](https://hub.docker.com/r/n24q02m/better-notion-mcp)\n[![License: MIT](https://img.shields.io/github/license/n24q02m/better-notion-mcp)](LICENSE)\n\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](#)\n[![Node.js](https://img.shields.io/badge/Node.js-5FA04E?logo=nodedotjs&logoColor=white)](#)\n[![Notion](https://img.shields.io/badge/Notion_API-000000?logo=notion&logoColor=white)](#)\n[![semantic-release](https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release&logoColor=white)](https://github.com/python-semantic-release/python-semantic-release)\n[![Renovate](https://img.shields.io/badge/renovate-enabled-1A1F6C?logo=renovatebot&logoColor=white)](https://developer.mend.io/)\n\n\n

Sister projects from n24q02m (click to expand)

\n\n| Project | Tagline | Tag |\n|---|---|---|\n| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |\n| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |\n| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |\n| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |\n| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |\n| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |\n| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |\n| [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |\n| [mcp-core](https://github.com/n24q02m/mcp-core) | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |\n| [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |\n| [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |\n| [skret](https://github.com/n24q02m/skret) | Secrets without the server. | CLI |\n| [tacet](https://github.com/n24q02m/tacet) | TACET: a self-distilling neuro-symbolic cascade that amortises LLM cost in kn... | Tooling |\n| [web-core](https://github.com/n24q02m/web-core) | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |\n| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |\n\n

\n\n\n## Table of contents\n\n- [Features](#features)\n- [Status](#status)\n- [Documentation](#documentation)\n- [Tools](#tools)\n- [Configuration](#configuration)\n- [Comparison](#comparison)\n- [Security](#security)\n- [Build from Source](#build-from-source)\n- [Trust Model](#trust-model)\n- [License](#license)\n\n\n\n\n $\"Better$ \n\n\n## Features\n\n- **Markdown in, Markdown out** -- human-readable content instead of raw JSON blocks\n- **11 composite tools** with 45 actions -- one call instead of chaining 2+ atomic endpoints\n- **Auto-pagination and bulk operations** -- no manual cursor handling or looping\n- **Tiered token optimization** -- ~77% reduction via compressed descriptions + on-demand `help` tool\n- **Dual transport** -- local stdio (token) or remote HTTP (OAuth 2.1, no token needed)\n\n## Status\n\n> **2026-05-02 -- Architecture stabilization update**\n>\n> 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.\n>\n> Apologies for the instability period. If you encountered issues with prior versions, please update to the latest release and follow the current [Setup guide](https://mcp.n24q02m.com/servers/better-notion-mcp/setup/) -- most prior workarounds are no longer needed.\n>\n> **Related plugins from the same author**:\n> - [wet-mcp](https://github.com/n24q02m/wet-mcp) -- Web search + content extraction\n> - [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) -- Persistent AI memory\n> - [imagine-mcp](https://github.com/n24q02m/imagine-mcp) -- Image/video understanding + generation\n> - [better-email-mcp](https://github.com/n24q02m/better-email-mcp) -- Email management\n> - [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) -- Telegram\n> - [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) -- Godot Engine\n> - [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) -- Code review knowledge graph\n>\n> All plugins share the same architecture -- install once, learn pattern transfers.\n\n## Documentation\n\nFull docs at **[mcp.n24q02m.com/servers/better-notion-mcp/](https://mcp.n24q02m.com/servers/better-notion-mcp/)**:\n\n- [Setup](https://mcp.n24q02m.com/servers/better-notion-mcp/setup/) -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json\n- [Modes overview](https://mcp.n24q02m.com/get-started/modes-overview/) -- stdio / local-relay / remote-relay / remote-oauth\n- [Multi-user setup](https://mcp.n24q02m.com/get-started/multi-user/) -- per-JWT-sub credential model\n\n**Install with AI agent** -- paste this to your AI coding agent:\n\n> Install MCP server `better-notion-mcp` following the steps at\n> https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-notion-mcp/setup-with-agent.md\n\n## Tools\n\n| Tool | Actions | Description |\n|:-----|:--------|:------------|\n| `pages` | `create`, `get`, `get_property`, `update`, `move`, `archive`, `restore`, `duplicate` | Create, read, update, and organize pages |\n| `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 |\n| `blocks` | `get`, `children`, `append`, `update`, `delete` | Read and manipulate block content |\n| `users` | `list`, `get`, `me`, `from_workspace` | List and retrieve user information |\n| `workspace` | `info`, `search` | Workspace metadata and cross-workspace search |\n| `comments` | `list`, `get`, `create` | Page and block comments |\n| `content_convert` | `markdown-to-blocks`, `blocks-to-markdown` | Convert between Markdown and Notion blocks |\n| `file_uploads` | `create`, `send`, `complete`, `retrieve`, `list` | Upload files to Notion |\n| `config` | `status`, `setup_start`, `setup_reset`, `setup_complete`, `set`, `cache_clear` | Manage server configuration and credential state via browser relay |\n| `config__open_relay` | - | Open the relay configuration form in the browser and return the relay URL + credential state |\n| `help` | - | Get full documentation for any tool |\n\n### MCP Resources\n\n| URI | Description |\n|:----|:------------|\n| `notion://docs/pages` | Page operations reference |\n| `notion://docs/databases` | Database operations reference |\n| `notion://docs/blocks` | Block operations reference |\n| `notion://docs/users` | User operations reference |\n| `notion://docs/workspace` | Workspace operations reference |\n| `notion://docs/comments` | Comment operations reference |\n| `notion://docs/content_convert` | Content conversion reference |\n| `notion://docs/file_uploads` | File upload reference |\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|:---------|:---------|:--------|:------------|\n| `NOTION_TOKEN` | Yes (stdio) | - | Notion integration token |\n| `TRANSPORT_MODE` | No | `stdio` | Set to `http` for remote mode |\n| `PUBLIC_URL` | No (http) | - | Server's public URL for OAuth redirect links |\n| `NOTION_OAUTH_CLIENT_ID` | Yes (http) | - | Notion Public Integration client ID |\n| `NOTION_OAUTH_CLIENT_SECRET` | Yes (http) | - | Notion Public Integration client secret |\n| `MCP_AUTH_DISABLE` | No (http) | - | Set to `1` to skip Bearer JWT verification when behind an external auth gateway |\n| `PORT` | No | `0` (OS-assigned) | Server port; set explicitly (e.g. `8080`) to bind a fixed port |\n| `HOST` | No | - | Bind address (http mode) |\n\n### Self-Hosting (Remote Mode)\n\nYou can self-host the remote server with your own Notion OAuth app.\n\n**Prerequisites:**\n1. Create a **Public Integration** at \n2. Set the redirect URI to `https://your-domain.com/callback`\n3. Note your `client_id` and `client_secret`\n\n```bash\ndocker run -p 8080:8080 \\\n -e TRANSPORT_MODE=http \\\n -e PORT=8080 \\\n -e PUBLIC_URL=https://your-domain.com \\\n -e NOTION_OAUTH_CLIENT_ID=your-client-id \\\n -e NOTION_OAUTH_CLIENT_SECRET=your-client-secret \\\n n24q02m/better-notion-mcp:latest\n```\n\n## Comparison\n\nHow better-notion-mcp stacks up against direct competitors in each pillar:\n\n| Capability | better-notion-mcp | makenotion/notion-mcp-server | suekou/mcp-notion-server | awkoy/notion-mcp-server |\n|---|---|---|---|---|\n| Markdown in / out | Yes (round-trip on pages + blocks) | No (raw Notion JSON) | partial (experimental, append + opt-in convert) | Yes (round-trip + GFM) |\n| Composite tool design | Yes (11 tools, 45 actions) | No (22 endpoint-mapped tools) | partial (simplified + raw JSON tools) | Yes (2 dispatch tools, 35+ ops) |\n| File uploads to Notion | Yes (`file_uploads`, single + multi-part) | No | No | Yes (`upload_file`, single + multi-part) |\n| Comments | Yes (`comments`: list/get/create) | Yes | Yes | Yes |\n| 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) |\n| Self-hostable | Yes (Docker, own OAuth app) | Yes | Yes | Yes |\n| License | MIT | ? | MIT | MIT |\n\n## Security\n\n- **OAuth 2.1 + PKCE S256** -- Secure authorization with code challenge\n- **Rate limiting** -- 120 req/min/IP on HTTP transport\n- **Session owner binding** -- IP check + TTL for pending token binds\n- **Null safety** -- Handles Notion API quirks (comments.list 404, undefined rich_text)\n\n## Build from Source\n\n```bash\ngit clone https://github.com/n24q02m/better-notion-mcp.git\ncd better-notion-mcp\nbun install\nbun run dev\n```\n\n## Trust Model\n\nThis plugin implements **TC-NearZK** (in-memory, ephemeral). See [the trust model reference](https://mcp.n24q02m.com/servers/mcp-core/trust-model/) for full classification.\n\n| Mode | Storage | Encryption | Who can read your data? |\n|---|---|---|---|\n| HTTP n24q02m-hosted (default) | In-memory `Map` | In-process only | Server process (cleared on restart) |\n| HTTP self-host | Same as hosted | Same | Only you (admin = user) |\n| 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 |\n\n## License\n\nMIT -- See [LICENSE](https://github.com/n24q02m/better-notion-mcp/blob/main/LICENSE).\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"categoryDisplayName","Developer Tools","upstream",{"_95":96,"_97":98,"_99":100,"_101":102,"_103":104},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_93":80,"_94":80},"ratingAvg","reviewCount","topics",[105,106,107,108,109,110,111,112,113,114,115,116,117,118],"license","MIT","language","TypeScript","registryName","io.github.n24q02m/better-notion-mcp","homepage","https://mcp.n24q02m.com/servers/better-notion-mcp/","ai-agents","ai-coding","claude","claude-code","cursor","docker","markdown","mcp","mcp-server","model-context-protocol","notion","notion-api","open-source","typescript","ENV",{"_121":122,"_123":124,"_125":126},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]