@n24q02m/better-notion-mcp 2.20.0 → 2.21.0

package/README.md

@@ -1,5 +1,7 @@
 # Better Notion MCP
 
+mcp-name: io.github.n24q02m/better-notion-mcp
+
 **Markdown-first Notion API server for AI agents -- 9 composite tools replacing 28+ endpoint calls**
 
 <!-- Badge Row 1: Status -->
@@ -32,11 +34,32 @@
 
 ### Claude Code Plugin (Recommended)
 
+Via marketplace (includes skills: /organize-database, /bulk-update):
+
+```bash
+/plugin marketplace add n24q02m/claude-plugins
+/plugin install better-notion-mcp@n24q02m-plugins
+```
+
+
+
+Plugin uses remote OAuth — no `NOTION_TOKEN` needed. Browser opens for Notion authorization on first use.
+
+### Gemini CLI Extension
+
 ```bash
-claude plugin add n24q02m/better-notion-mcp
+gemini extensions install https://github.com/n24q02m/better-notion-mcp
 ```
 
-Uses remote OAuth -- no `NOTION_TOKEN` needed. Your browser opens for Notion authorization on first use.
+### Codex CLI
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.better-notion-mcp]
+command = "npx"
+args = ["-y", "@n24q02m/better-notion-mcp"]
+```
 
 ### MCP Server
 
@@ -59,15 +82,20 @@ Connect directly via URL with OAuth authentication. Your MCP client handles the
 
 Get your token: <https://www.notion.so/my-integrations> -> Create integration -> Copy token -> Share pages
 
+Set `NOTION_TOKEN` in `~/.claude/settings.local.json` or your shell profile:
+
+```bash
+export NOTION_TOKEN="ntn_..."
+```
+
+Then add to your MCP client config:
+
 ```jsonc
 {
   "mcpServers": {
     "better-notion": {
       "command": "npx",
-      "args": ["-y", "@n24q02m/better-notion-mcp@latest"],
-      "env": {
-        "NOTION_TOKEN": "ntn_..."
-      }
+      "args": ["-y", "@n24q02m/better-notion-mcp@latest"]
     }
   }
 }
@@ -86,34 +114,12 @@ Other runners: `bun x`, `pnpm dlx`, `yarn dlx` also work.
         "run", "-i", "--rm",
         "-e", "NOTION_TOKEN",
         "n24q02m/better-notion-mcp:latest"
-      ],
-      "env": {
-        "NOTION_TOKEN": "ntn_..."
-      }
+      ]
     }
   }
 }
 ```
 
-### Self-Hosting (Remote Mode)
-
-You can self-host the remote server with your own Notion OAuth app.
-
-**Prerequisites:**
-1. Create a **Public Integration** at <https://www.notion.so/my-integrations>
-2. Set the redirect URI to `https://your-domain.com/callback`
-3. Note your `client_id` and `client_secret`
-
-```bash
-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
-```
-
 ## Tools
 
 | Tool | Actions | Description |
@@ -128,6 +134,32 @@ docker run -p 8080:8080 \
 | `file_uploads` | `create`, `send`, `complete`, `retrieve`, `list` | Upload files to Notion |
 | `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:
+
+1. Start the server (via plugin, `npx`, or Docker)
+2. A setup URL appears -- open it in any browser
+3. Fill in your credentials on the guided form
+4. 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 |
@@ -140,41 +172,40 @@ docker run -p 8080:8080 \
 | `DCR_SERVER_SECRET` | Yes (http) | - | HMAC secret for stateless client registration |
 | `PORT` | No | `8080` | Server port |
 
-## Build from Source
+### Self-Hosting (Remote Mode)
 
-```bash
-git clone https://github.com/n24q02m/better-notion-mcp.git
-cd better-notion-mcp
-npm install
-npm run build
-npm start
-```
+You can self-host the remote server with your own Notion OAuth app.
 
-## Compatible With
+**Prerequisites:**
+1. Create a **Public Integration** at <https://www.notion.so/my-integrations>
+2. Set the redirect URI to `https://your-domain.com/callback`
+3. Note your `client_id` and `client_secret`
 
-[![Claude Code](https://img.shields.io/badge/Claude_Code-000000?logo=anthropic&logoColor=white)](#quick-start)
-[![Claude Desktop](https://img.shields.io/badge/Claude_Desktop-F9DC7C?logo=anthropic&logoColor=black)](#quick-start)
-[![Cursor](https://img.shields.io/badge/Cursor-000000?logo=cursor&logoColor=white)](#quick-start)
-[![VS Code Copilot](https://img.shields.io/badge/VS_Code_Copilot-007ACC?logo=visualstudiocode&logoColor=white)](#quick-start)
-[![Antigravity](https://img.shields.io/badge/Antigravity-4285F4?logo=google&logoColor=white)](#quick-start)
-[![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-8E75B2?logo=googlegemini&logoColor=white)](#quick-start)
-[![OpenAI Codex](https://img.shields.io/badge/Codex-412991?logo=openai&logoColor=white)](#quick-start)
-[![OpenCode](https://img.shields.io/badge/OpenCode-F7DF1E?logoColor=black)](#quick-start)
+```bash
+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
+```
 
-## Also by n24q02m
+## Security
 
-| Server | Description |
-|--------|-------------|
-| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Web search, content extraction, and documentation indexing |
-| [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and cross-machine sync |
-| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | Email (IMAP/SMTP) with multi-account and auto-discovery |
-| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Godot Engine 4.x with 18 tools for scenes, scripts, and shaders |
-| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | Telegram dual-mode (Bot API + MTProto) with 6 composite tools |
-| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews |
+- **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)
 
-## Contributing
+## Build from Source
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+```bash
+git clone https://github.com/n24q02m/better-notion-mcp.git
+cd better-notion-mcp
+bun install
+bun run dev
+```
 
 ## License