# better-notion-mcp

Hands an agent access to Notion pages, databases, blocks and comments, with Markdown going in and coming back out instead of raw JSON blocks.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 35
- Author: n24q02m
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/n24q02m/notion
- Updated: 2026-10-11
- HTML: https://affpapa.org/en/nevibecode/mcp/better-notion-mcp

## What it does

Getting one thing done through the Notion API usually means chaining several endpoint calls. This server folds that into a single call: 8 composite tools carrying 39 actions cover pages, databases, blocks and comments. Content travels as Markdown both ways, so the agent reads and writes plain text rather than JSON block trees.

Cursor handling and bulk operations ship with the tools, which drops the hand-written loop. Tool descriptions stay short and the agent pulls detail from a separate `help` tool only when it needs it, trimming token spend by roughly 77%. The npm package is `@n24q02m/notion`; the older `@n24q02m/better-notion-mcp` name and the `better-notion-mcp` command still resolve as an alias.

Two ways to connect: local stdio with an integration token, or the hosted HTTP mode that authenticates over OAuth 2.1 and asks for no token in your config. Stdio needs Node.js 24 or newer — anything older will not start the package through `npx`. Grab the token at `https://www.notion.so/my-integrations`; it begins with `ntn_`.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `NOTION_TOKEN` — keys and tokens: ask the human for the values, never commit them or put them in shared files.
- Works with: Notion

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add better-notion-mcp -e NOTION_TOKEN=<NOTION_TOKEN> -- npx -y @n24q02m/better-notion-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add better-notion-mcp --env NOTION_TOKEN=<NOTION_TOKEN> -- npx -y @n24q02m/better-notion-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "better-notion-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@n24q02m/better-notion-mcp"
            ],
            "env": {
                "NOTION_TOKEN": "<NOTION_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "better-notion-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@n24q02m/better-notion-mcp"
            ],
            "env": {
                "NOTION_TOKEN": "<NOTION_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e NOTION_TOKEN=<NOTION_TOKEN> better-notion-mcp npx -y @n24q02m/better-notion-mcp
```
Replace <…> with your own values

## When to use it
- read a Notion page and hand back its content as Markdown
- add a database row from text the agent just wrote
- walk a long block list without writing a pagination loop
- pull every comment on a page in one call
- push a batch of rows into a database at once

## Example prompts
- Find the release notes page in Notion and rewrite the migration section as Markdown.
- Create a task in the bugs database for the auth failure and post a comment linking the log.
- List every block on the `Roadmap` page and draft a summary from them.

## Similar
- [Reactive Resume](https://affpapa.org/en/nevibecode/mcp/reactive-resume.md) — MCP server · ★ 44874
- [screenpipe](https://affpapa.org/en/nevibecode/mcp/screenpipe.md) — MCP server · ★ 22053
- [Inbox Zero](https://affpapa.org/en/nevibecode/mcp/inbox-zero.md) — MCP server · ★ 12791
- [kaneo](https://affpapa.org/en/nevibecode/mcp/kaneo.md) — MCP server · ★ 9602
- [Mindwtr](https://affpapa.org/en/nevibecode/mcp/mindwtr.md) — MCP server · ★ 2318
- [Azure DevOps (ADO)](https://affpapa.org/en/nevibecode/mcp/azure-devops-ado.md) — MCP server · ★ 2067

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md