# better-notion-mcp

The better-notion-mcp server lets an AI agent work with Notion pages, databases, blocks, and comments using Markdown. Use it when an agent needs to read or edit workspace content.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 36 repo stars
- 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-28
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/n24q02m-better-notion-mcp

## What it does

better-notion-mcp exchanges Notion content with an agent as Markdown rather than raw JSON blocks. It provides 8 composite tools covering 39 actions, grouping work that would otherwise require several separate Notion calls. Pagination and bulk operations are handled automatically.

Choose local stdio with a Notion integration token, or remote HTTP with OAuth 2.1. Local setup requires Node.js version 24 or later and a Notion token supplied as `NOTION_TOKEN`. The local connection will not work without that integration token.

## 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/notion
```
Replace <…> with your own values

### Codex

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

### Cursor

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

### GitHub Copilot

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

### Gemini CLI

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

## When to use it
- create a Notion page from Markdown
- find and update database entries
- read the blocks on a page
- add a comment to a page
- process multiple Notion items in one request

## Example prompts
- Create a Notion page from this Markdown and place it in the right section.
- Find database entries matching this condition and update them.
- Read the blocks on this Notion page, then add a comment.

## Similar
- [easy-notion](https://affpapa.org/en/nevibecode/mcp/easy-notion.md) — MCP server · ★ 56 repo stars
- [WireCat notion](https://affpapa.org/en/nevibecode/mcp/wirecat-notion.md) — MCP server · ★ 1 repo stars
- [Notion](https://affpapa.org/en/nevibecode/mcp/makenotion-notion.md) — MCP server
- [pp-notion](https://affpapa.org/en/nevibecode/skills/pp-notion.md) — skill · 394 installs
- [notion-meeting-intelligence](https://affpapa.org/en/nevibecode/skills/openai-notion-meeting-intelligence.md) — skill · 3400 installs
- [notion-mcp](https://affpapa.org/en/nevibecode/skills/notion-mcp.md) — skill · 878 installs

---
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
