io.github.misterwigglesworth/easy-notion

Install

Config snippet generator goes here (5 client tabs)

README

<div align="center">

# Easy Notion MCP

**Markdown-first MCP server that connects AI agents to Notion.**<br>
Agents write markdown — easy-notion-mcp converts it to Notion's block API and back again.

26 tools · 25 block types · 92% fewer tokens vs official Notion MCP · Full round-trip fidelity

[![npm](https://img.shields.io/npm/v/easy-notion-mcp)](https://www.npmjs.com/package/easy-notion-mcp)
[![license](https://img.shields.io/npm/l/easy-notion-mcp)](LICENSE)
[![node](https://img.shields.io/node/v/easy-notion-mcp)](package.json)

```bash
npx easy-notion-mcp
```

**[See it in action →](https://www.notion.so/easy-notion-mcp-327be876242f817f9129ff1a5a624814)** Live Notion page created and managed entirely through easy-notion-mcp.

</div>

![Raw JSON chaos vs clean markdown](assets/readme-banner.png)

---

**Contents:** [Comparison](#how-does-easy-notion-mcp-compare-to-other-notion-mcp-servers) · [Setup](#how-do-i-set-up-easy-notion-mcp) · [Why markdown](#why-markdown-first) · [How it works](#how-does-easy-notion-mcp-work) · [Tools](#what-tools-does-easy-notion-mcp-provide) · [Block types](#what-block-types-does-easy-notion-mcp-support) · [Round-trip](#can-i-read-and-rewrite-pages-without-losing-formatting) · [Databases](#how-does-easy-notion-mcp-handle-databases) · [Config](#configuration) · [Security](#what-about-security-and-prompt-injection) · [FAQ](#frequently-asked-questions)

## How does easy-notion-mcp compare to other Notion MCP servers?

| Feature | easy-notion-mcp | Official Notion MCP (npm) | better-notion-mcp |
|---|---|---|---|
| **Content format** | ✅ Standard GFM markdown | ❌ Raw Notion API JSON | ⚠️ Markdown (limited block types) |
| **Block types** | ✅ 25 (toggles, columns, callouts, equations, embeds, tables, file uploads, task lists) | ⚠️ All (as raw JSON) | ⚠️ ~7 (headings, paragraphs, lists, code, quotes, dividers) |
| **Round-trip fidelity** | ✅ Full — read markdown, modify, write back | ❌ Raw JSON requires block reconstruction | ⚠️ Unsupported blocks silently dropped |
| **Tools** | 26 individually-named tools | 18 auto-generated from OpenAPI | 9 composite tools (39 actions) |
| **File uploads** | ✅ `file:///path` in markdown | ❌ [Open feature request](https://github.com/makenotion/notion-mcp-server/issues/191) | ✅ 5-step lifecycle |
| **Prompt injection defense** | ✅ Content notice prefix + URL sanitization | ❌ | ❌ |
| **Database entry format** | Simple `{"Status": "Done"}` key-value pairs | Simplified key-value pairs | Simplified key-value pairs |
| **Auth options** | API token or OAuth | API token or OAuth | API token or OAuth |

### How many tokens does easy-notion-mcp save?

| Operation | easy-notion-mcp | better-notion-mcp | Official Notion MCP | Savings vs Official |
|---|---|---|---|---|
| Page read | **291 tokens** | ⚠️ 236 tokens | 6,536 tokens | **95.5%** |
| DB query (5 rows) | **347 tokens** | 704 tokens | 2,983 tokens | **88.4%** |
| Search (3 results) | **298 tokens** | 347 tokens | 1,824 tokens | **83.7%** |

⚠️ better-notion-mcp page reads appear smaller because they silently drop 11 block types (callouts, toggles, tables, task lists, equations, bookmarks, embeds). On equal content coverage, easy-notion-mcp is more efficient.

*Measured by running all three MCP servers against the same Notion content and counting tokens with tiktoken cl100k_base. Raw responses saved for verification.*

## How do I set up easy-notion-mcp?

### With OAuth (recommended)

Run the HTTP server, then connect with any MCP client. OAuth handles authentication — no token to copy-paste.

**Start the server:**

```bash
npx easy-notion-mcp-http
```

Requires `NOTION_OAUTH_CLIENT_ID` and `NOTION_OAUTH_CLIENT_SECRET` env vars. See [OAuth setup](#oauth--http-transport) below.

**Claude Code:**

```bash
claude mcp add notion --transport http http://localhost:3333/mcp
```

**OpenClaw:**

```bash
openclaw config set mcpServers.notion.transport "http"
openclaw config set mcpServers.notion.url "http://localhost:3333/mcp"
```

**Claude Desktop:**

Go to Settings → Connectors → Add custom connector, enter `http://localhost:3333/mcp`.

Your browser will open to Notion's authorization page. Pick the pages to share, click Allow, done.

### With API token

Create a [Notion integration](https://www.notion.so/my-integrations), copy the token, share your pages with it.

**Claude Code:**

```bash
claude mcp add notion -- npx -y easy-notion-mcp
```

Set the env var: `export NOTION_TOKEN=ntn_your_integration_token`

**OpenClaw:**

```bash
openclaw config set mcpServers.notion.command "npx"
openclaw config set mcpServers.notion.args '["easy-notion-mcp"]'
```

Set the env var: `export NOTION_TOKEN=ntn_your_integration_token`

**Claude Desktop / Cursor / Windsurf** — add to your MCP config file:

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "easy-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_token"
      }
    }
  }
}
```

Config file locations: Cl