Grey-Iris/easy-notion-mcp

**Markdown-first MCP server that connects AI agents to Notion.**
Agents write markdown — easy-notion-mcp converts it to Notion's block API and back again.
43 tools · 24 block types · ~6–7× fewer response tokens vs official Notion MCP · Documented round-trip support
**See it in action →** Live Notion page created and managed entirely through easy-notion-mcp.
---
**Contents:** Comparison · Setup · CLI profiles · Config · Why markdown · How it works · Tools · MCP resources · Block types · Round-trip · Databases · Cookbook · Security · Stability · FAQ · Community
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** | ✅ 24 (toggles, columns, callouts, equations, embeds, tables, file uploads, task lists) | ⚠️ All (as raw JSON) | ⚠️ ~7 (headings, paragraphs, lists, code, quotes, dividers) |
| **Round-trip support** | ✅ 24 block types, documented caveats | ❌ Raw JSON requires block reconstruction | ⚠️ Unsupported blocks silently dropped |
| **Tools** | 43 individually-named tools | 18 auto-generated from OpenAPI | 9 composite tools (39 actions) |
| **File uploads** | ✅ file:///path in markdown | ❌ Open feature request | ✅ 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?
Reading a page's content costs about **6–7× fewer response tokens** than the official Notion MCP server, because Notion's raw block JSON carries per-block metadata (block IDs, timestamps, author objects) that an agent reading for content never needs. Typically ~5–7×, ranging from ~3× on code-heavy pages to ~15× on rich pages, with ≥94% of the page's content preserved. Measured against the official raw-JSON server; roughly on par with other markdown-based servers.
The win is metadata omission, not encoding efficiency. At equal information the two formats cost about the same (the common intermediate-representation ratio is ~1.0–1.06× on fully represented page shapes, and 1.32× on typical prose), so the saving is the per-block metadata (block UUIDs, timestamps, author objects, annotation wrappers) that raw JSON carries and a content read never uses. Database queries show a similar ~7× win at full content completeness.
Methodology, per-class results, and every caveat: .meta/research/token-bench-results-2026-06-13.md (re-run via scripts/bench/lib/recompute-tiers.ts).
How do I set up easy-notion-mcp?
With API token
Create a Notion integration, copy the token, share your pages with it.
**Claude Code:**
This registers the server in your Claude Code **user-level** config (-s user) and passes NOTION_TOKEN directly to the MCP child process via -e. Your shell environment and rcfiles are untouched — the token lives in Claude Code's config file, scoped to this server, and is not visible to other processes. To set a default parent page for create_page, add -e NOTION_ROOT_PAGE_ID= to the same command.
**OpenClaw:**
Then provide the token via the parent shell environment before starting OpenClaw:
This export form is the generic fallback for any MCP client that inherits the parent shell environment. Caveat: it only persists for the current shell session unless you add it to your shell rcfile, which has its own security implications — prefer the -e form above when using Claude Code specifically.
**Claude Desktop / Cursor / Windsurf** — add to your MCP config file:
Config file locations: Claude Desktop → claude_desktop_config.json · Cursor → .cursor/mcp.json · Windsurf → ~/.windsurf/mcp.json
VS Code Copilot — add to .vscode/mcp.json (uses servers not mcpServers )
CLI profiles for low-context Notion access
Use the easy-notion CLI when an agent needs Notion access without loading the full MCP tool surface, or when you want separate Notion integrations for different permission modes. Profiles live in ~/.config/easy-notion-mcp/profiles.json by default and reference environment variable names, not raw tokens.
Read commands work with readonly profiles:
Mutating commands require a readwrite profile:
Destructive CLI commands support --dry-run as a readonly preflight. It runs