easy-notion-mcp

Production-oriented MCP server that connects AI agents to Notion through standard markdown instead of raw API JSON.

Agents read and write GFM markdown. The server handles block conversion, database schema mapping, OAuth, and optional Redis-backed persistence for multi-instance deployments.

Feature highlights

Architecture

flowchart TB
  subgraph clients [MCP Clients]
    CC[Claude Code / Cursor]
    HTTP[HTTP MCP clients]
  end

  subgraph transport [Transport Layer]
    STDIO[index.ts — stdio]
    HTTP_SRV[http.ts — Express]
  end

  subgraph core [Application Core]
    SRV[server.ts — MCP tools & resources]
    NC[notion-client.ts — Notion SDK wrapper]
    MD[markdown converters]
  end

  subgraph persistence [Persistence — optional]
    MEM[(In-memory cache)]
    REDIS[(Redis)]
    FS[(Encrypted token files)]
  end

  CC --> STDIO
  HTTP --> HTTP_SRV
  STDIO --> SRV
  HTTP_SRV --> SRV
  SRV --> NC
  SRV --> MD
  NC --> MEM
  NC --> REDIS
  HTTP_SRV --> FS
  HTTP_SRV --> REDIS

Request workflow (tool call)

sequenceDiagram
  participant Agent
  participant MCP as MCP Server
  participant Cache as Cache Store
  participant Notion as Notion API

  Agent->>MCP: tools/call (e.g. read_page)
  MCP->>Notion: blocks.children.list (paginated)
  Notion-->>MCP: block tree
  MCP->>MCP: blocks → markdown
  MCP-->>Agent: { markdown, warnings? }

  Agent->>MCP: tools/call (add_database_entry)
  MCP->>Cache: get schema:dbId
  alt cache miss
    Cache->>Notion: dataSources.retrieve
    Notion-->>Cache: schema
    Cache-->>MCP: schema
  else cache hit
    Cache-->>MCP: schema
  end
  MCP->>MCP: convert property values
  MCP->>Notion: pages.create
  Notion-->>MCP: page
  MCP-->>Agent: { id, url }

Project structure

easy-notion-mcp/
├── src/
│   ├── index.ts              # Stdio entry point
│   ├── http.ts               # HTTP/OAuth entry point
│   ├── cli.ts                # Profile-based CLI
│   ├── server.ts             # MCP tool & resource handlers
│   ├── notion-client.ts      # Notion SDK integration
│   ├── config/env.ts         # Typed environment parsing
│   ├── logging/logger.ts     # Structured logging
│   ├── persistence/          # Cache + Redis integration
│   │   ├── cache-store.ts
│   │   ├── init.ts
│   │   └── redis/
│   └── auth/                   # OAuth token storage
├── tests/                    # Vitest unit & integration tests
├── docs/AUDIT.md             # Engineering audit notes
├── skills/                   # Agent skill definitions
└── dist/                     # Compiled output (generated)

Design decisions

• Single server module — tool handlers remain in server.ts to preserve the stable public MCP contract; supporting modules handle cross-cutting concerns.
• Pluggable cache — CacheStore abstraction allows in-memory (default) or Redis backends without changing Notion client logic.
• Fail-open Redis — if Redis is configured but unreachable, the server logs a warning and continues with in-memory/file persistence.

Installation

Prerequisites

• Node.js 20+
• A Notion integration with pages shared to it

From source

git clone https://github.com/Grey-Iris/easy-notion-mcp.git
cd easy-notion-mcp
npm install
npm run build

Via npx (published package)

npx -y easy-notion-mcp

MCP client configuration (stdio)

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

Configuration

Copy .env.example to .env when running from a cloned checkout:

cp .env.example .env

Core variables

Redis persistence (optional)

Example with local Redis:

REDIS_ENABLED=true REDIS_URL=redis://127.0.0.1:6379/0 npm start

HTTP transport

Development

# Install dependencies
npm install

# Watch mode
npm run dev

# Run stdio server locally
NOTION_TOKEN=ntn_... npm start

# Run HTTP server
NOTION_TOKEN=ntn_... NOTION_MCP_BEARER=$(openssl rand -hex 32) npm run start:http

Quality gates

npm run build      # Compile TypeScript
npm run typecheck  # Type check without emit
npm run lint       # ESLint
npm test           # Vitest unit tests

Testing

# Full unit suite (~850 tests)
npm test

# Watch mode
npm run test:watch

# Live Notion E2E (requires dedicated test workspace)
cp .env.example .env   # set E2E_ROOT_PAGE_ID
npm run test:e2e

Symlink-dependent security tests are automatically skipped on platforms where symlink creation is unavailable (common on Windows without Developer Mode).

Troubleshooting

Enable debug logging:

LOG_LEVEL=debug npm start

Contributing

1. Fork the repository and create a feature branch from main
2. Make focused changes with tests where behavior changes
3. Run npm run build && npm run lint && npm test
4. Open a pull request with a clear description and test plan

See docs/AUDIT.md for architecture context and known improvement areas.

FAQ

How is this different from the official Notion MCP server?
The official server returns raw Notion JSON (~6–7× more tokens per page read). This server converts to markdown agents already understand, with round-trip fidelity for 24 block types.

Do I need Redis?
No. Redis is optional and improves horizontal scaling (shared schema cache, OAuth tokens across HTTP instances). Single-process stdio deployments work fine without it.

Is markdown round-trip lossless?
For supported block types, yes. Unsupported native blocks (e.g. synced_block, embedded databases) emit warnings so agents avoid destructive rewrites.

Does file upload work over HTTP?
No. file:// uploads are stdio-only for security. Use HTTPS URLs or stdio transport for local files.

What Node version is required?
Node.js 20 or later.

License

MIT — see LICENSE.