AI 에이전트를 원시 API JSON 대신 표준 마크다운으로 Notion에 연결하는 운영 지향 MCP 서버입니다.

에이전트는 GFM 마크다운을 읽고 씁니다. 서버는 블록 변환, 데이터베이스 스키마 매핑, OAuth, 그리고 다중 인스턴스 배포를 위한 선택적 Redis 지원 영속성을 처리합니다.

---

특집 하이라이트

---

건축

작업 흐름 요청 (툴 호출)

---

프로젝트 구조

디자인 결정

• 단일 서버 모듈 — 툴 핸들러는 'server.'에 남습니다.

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