# easy-notion [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/Grey-Iris/easy-notion-mcp  
**GitHub Stars:** 55  
**npm Downloads (last month):** 2463  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/easy-notion

## Description
Markdown-first Notion MCP server. ~6-7x fewer response tokens vs official Notion MCP. 43 tools.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `NOTION_TOKEN`, `NOTION_OAUTH_CLIENT_ID`, `NOTION_OAUTH_CLIENT_SECRET`, `NOTION_ROOT_PAGE_ID` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/easy-notion/readme_