面向生产环境的MCP服务器，通过标准markdown而非原始API JSON将AI代理连接到Notion。

代理负责读写GFM markdown。服务器负责块转换、数据库模式映射、OAuth以及可选的Redis支持持久化，用于多实例部署。

---

特色亮点

---

建筑

请求工作流程（工具调用）

---

项目结构

设计决策

• 单一服务器模块 — 工具处理器仍保留在“服务器”中。

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