# easy-notion

An MCP server that hands your agent Notion pages as plain markdown. Useful when you read and edit pages instead of parsing raw JSON.

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

## What it does

The agent writes markdown; the server turns it into Notion blocks and back. It ships 43 tools and covers 24 block types, among them toggles, columns, callouts, equations, embeds, tables, file uploads and task lists. Reading a page costs far fewer response tokens than the official Notion server, since the payload skips per-block bookkeeping such as block IDs, timestamps and author objects. That omission is where the saving comes from, not the encoding.

Installation runs through `npx`, and a Notion token is required either way. Create a Notion integration, copy the token, then share the pages with it — otherwise the server sees nothing. In Claude the token goes in with the `-e` flag and stays in the config file, leaving your shell and rcfiles alone. A default parent page for `create_page` is set with `NOTION_ROOT_PAGE_ID`.

CLI profiles keep separate integrations for different permission modes, say read-only and read-write, and store environment variable names rather than raw tokens. They live in `~/.config/easy-notion-mcp/profiles.json`. Reach for them when an agent needs Notion without loading the whole MCP tool surface.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `NOTION_TOKEN`, `NOTION_ROOT_PAGE_ID` — 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 --env NOTION_TOKEN=<NOTION_TOKEN> --env NOTION_ROOT_PAGE_ID=<NOTION_ROOT_PAGE_ID> --transport stdio easy-notion -- npx -y easy-notion-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add easy-notion --env NOTION_TOKEN=<NOTION_TOKEN> --env NOTION_ROOT_PAGE_ID=<NOTION_ROOT_PAGE_ID> -- npx -y easy-notion-mcp
```
Replace <…> with your own values

### Cursor

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

### GitHub Copilot

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

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e NOTION_TOKEN=<NOTION_TOKEN> -e NOTION_ROOT_PAGE_ID=<NOTION_ROOT_PAGE_ID> easy-notion npx -y easy-notion-mcp
```
Replace <…> with your own values

## When to use it
- read a Notion page and get it back as markdown
- build a page with nested blocks from a markdown file
- rewrite a page while keeping its formatting
- upload a file to Notion from a `file:///path` reference
- give an agent read-only access to Notion

## Example prompts
- Read the Notion page and show me its contents as markdown
- Create a Notion page from `notes.md`
- Update the Notion page: replace the text in the first section

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

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