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

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:

claude mcp add notion -s user \
  -e NOTION_TOKEN=ntn_your_integration_token \
  -- npx -y easy-notion-mcp

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=<page-id> to the same command.

OpenClaw:

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

Then provide the token via the parent shell environment before starting OpenClaw:

export NOTION_TOKEN=ntn_your_integration_token

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:

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

Config file locations: Claude Desktop → claude_desktop_config.json · Cursor → .cursor/mcp.json · Windsurf → ~/.windsurf/mcp.json

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

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.

export NOTION_WORK_READONLY=ntn_readonly_token
export NOTION_WORK_WRITE=ntn_readwrite_token

npx -y --package easy-notion-mcp easy-notion profile add work-ro \
  --token-env NOTION_WORK_READONLY \
  --mode readonly \
  --default

npx -y --package easy-notion-mcp easy-notion profile add work-rw \
  --token-env NOTION_WORK_WRITE \
  --mode readwrite \
  --root-page-id your_root_page_id

Read commands work with readonly profiles:

npx -y --package easy-notion-mcp easy-notion --profile work-ro search "roadmap" --filter pages
npx -y --package easy-notion-mcp easy-notion --profile work-ro page read PAGE_ID --include-metadata
npx -y --package easy-notion-mcp easy-notion --profile work-ro content search-in-page PAGE_ID --query "launch" --within-toggle "Script"

Mutating commands require a readwrite profile:

npx -y --package easy-notion-mcp easy-notion --profile work-rw content append PAGE_ID --markdown "## Update"
npx -y --package easy-notion-mcp easy-notion --profile work-rw content update-toggle PAGE_ID --title "Script" --markdown-file ./script.md
npx -y --package easy-notion-mcp easy-notion --profile work-rw content archive-toggle PAGE_ID --title "Done"
npx -y --package easy-notion-mcp easy-notion --profile work-rw content restore-toggle ARCHIVED_BLOCK_ID

Destructive CLI commands support --dry-run as a readonly preflight. It runs the same lookup and markdown validation where possible, returns planned fields such as would_delete_block_ids, would_update, would_archive, or would_restore, and does not mutate Notion.

The lightweight skill for agent routing is published in this repo at skills/easy-notion-cli/. It teaches agents to prefer the CLI for profile-based Notion access instead of registering multiple MCP servers.

With OAuth

API-token + stdio is the lower-friction default. If you're running a shared deployment or want per-user access, OAuth handles authentication with no token to copy-paste.

Start the server:

npx -p easy-notion-mcp easy-notion-mcp-http

Requires NOTION_OAUTH_CLIENT_ID and NOTION_OAUTH_CLIENT_SECRET env vars. See OAuth setup below.

Claude Code:

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

OpenClaw:

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.

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