Log inSubmit server
Easy Notion logo

Easy Notion

Markdown-first Notion MCP server that converts agent-written Markdown to Notion blocks and back.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Easy Notion

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "easy-notion": {
      "command": "npx",
      "args": [
        "-y",
        "easy-notion-mcp"
      ],
      "env": {
        "NOTION_TOKEN": "YOUR_VALUE_HERE",
        "NOTION_OAUTH_CLIENT_ID": "YOUR_VALUE_HERE",
        "NOTION_OAUTH_CLIENT_SECRET": "YOUR_VALUE_HERE",
        "NOTION_ROOT_PAGE_ID": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y easy-notion-mcp

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 25d ago.

Overview

The easy-notion MCP server connects AI agents to Notion using standard GitHub-Flavored Markdown instead of raw block JSON. It converts Markdown into Notion blocks and renders Notion content back to Markdown, supporting 24 block types across 43 individually named tools. Use it for reading, creating, updating, searching, and managing Notion pages and database entries when compact responses and readable content matter. It runs through stdio with an API token or through HTTP with OAuth support.

Use cases

  • Read Notion pages as compact Markdown
  • Create and update workspace documentation
  • Search page content for project information
  • Manage database entries with key-value properties
  • Separate read-only and read-write Notion access

Key features

  • Markdown-to-Notion block conversion
  • Notion-to-Markdown page reads
  • Support for 24 block types
  • 43 individually named MCP tools
  • API token and OAuth authentication
  • Read-only and read-write CLI profiles

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

8/8 checks healthy over the last 40d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d ago via OSV.dev · easy-notion-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars55Stargazers on the source repository.
npm downloads2.6kPackage downloads in the last 30 days.
Last commit1mo agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Directory activity3 viewsConfig copies, upvotes, and views on AllMCPs.

How Easy Notion works

What easy-notion does

easy-notion MCP server connects AI agents to Notion and uses Markdown as the primary content format. Agents can provide Markdown for page content, while the server translates it into Notion's block API. Content read from Notion is converted back into Markdown, giving agents a compact representation that avoids exposing block IDs, timestamps, author objects, and other metadata in every response.

The project provides 43 individually named tools and supports 24 Notion block types. Supported content includes common text and list structures as well as toggles, columns, callouts, equations, embeds, tables, file uploads, and task lists.

For the 🏢 Workplace & Productivity category, easy-notion is relevant when an agent needs to maintain documentation, project pages, notes, or structured workspace content in Notion.

How it works

With an API-token configuration, the server starts as a stdio MCP process, commonly through npx -y easy-notion-mcp. The MCP client passes NOTION_TOKEN to the process, and the Notion integration must have access to the pages it will use.

The conversion layer accepts standard GitHub-Flavored Markdown and maps it to Notion blocks. On reads, it produces Markdown rather than raw Notion API objects. The README reports roughly 6–7 times fewer response tokens than the official raw-JSON Notion MCP in typical page reads, with results varying by page content and block types.

An HTTP command, easy-notion-mcp-http, is available for OAuth-based deployments. OAuth requires NOTION_OAUTH_CLIENT_ID and NOTION_OAUTH_CLIENT_SECRET, making that option applicable when a shared deployment or per-user authorization flow is preferred.

Setup and configuration

Install and start the package with npx, then configure the MCP client to run it. The README gives configurations for Claude Desktop, Cursor, Windsurf, and VS Code Copilot, with VS Code using a servers object rather than mcpServers. Claude Code can register the server with claude mcp add and pass the token using -e.

Set NOTION_TOKEN for API-token authentication. An optional NOTION_ROOT_PAGE_ID supplies a default parent page for page creation. The required Notion integration must be created in Notion and granted access to the relevant pages.

The package also includes an easy-notion CLI. Profiles can point to environment-variable names instead of storing raw tokens, and can use read-only or read-write modes. Profiles may also define a default root page. Read-only commands include page reads and searches; mutating commands include content append, toggle updates, archiving, and restoration. Destructive commands support a --dry-run preflight.

Tools and capabilities

  • Read and write Notion page content through Markdown.
  • Search Notion and search within page content.
  • Create and manage page content and database entries.
  • Work with 24 documented block types.
  • Upload files referenced with file:///path in Markdown.
  • Use individually named MCP tools rather than a smaller set of composite actions.
  • Use CLI profiles to separate read-only and read-write access modes.

Limitations and notes

easy-notion MCP server still follows Notion API permissions: the integration must be given access to pages it needs to read or change.

Token savings come primarily from omitting per-block metadata in responses, not from making the underlying information intrinsically more compressed. The reported comparison is against the official raw-JSON Notion MCP and varies by page composition. API-token plus stdio is described as the lower-friction default, while OAuth requires additional client credentials and the HTTP command.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Easy Notion

easy-notion is an MCP server that connects AI agents to Notion and exposes tools for Markdown-based page content, searches, page operations, and database entries. It converts GitHub-Flavored Markdown into Notion blocks and converts supported Notion blocks back to Markdown, covering 24 block types through 43 individually named tools.

Install it through `npx -y easy-notion-mcp` in your MCP client configuration. Set `NOTION_TOKEN` to a Notion integration token and share the required pages with that integration. The README includes configuration examples for Claude Desktop, Cursor, Windsurf, VS Code, and Claude Code.

Yes, easy-notion works with Cursor through its MCP configuration file. Add an entry that runs `npx` with `-y` and `easy-notion-mcp`, then provide `NOTION_TOKEN` in the `env` object. The README identifies `.cursor/mcp.json` as Cursor's configuration location.

Yes, easy-notion supports OAuth through its HTTP command, `npx -p easy-notion-mcp easy-notion-mcp-http`. OAuth configuration requires `NOTION_OAUTH_CLIENT_ID` and `NOTION_OAUTH_CLIENT_SECRET`. API-token authentication over stdio is the documented lower-friction option.

Yes, the included CLI supports read-only profiles. A profile references an environment variable containing the token and uses `--mode readonly`; read commands such as search and page reads remain available, while mutating commands require a read-write profile.

Related MCP servers

All in Workplace & Productivity All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewEasy Notion AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/easy-notion?style=directory)](https://allmcps.com/mcp/easy-notion)
HTML Embed
<a href="https://allmcps.com/mcp/easy-notion"><img src="https://allmcps.com/api/badge/easy-notion?style=directory" alt="Easy Notion on AllMCPs" /></a>