项目概述

核心定位

该项目是 MCP 协议在 Notion 生态中的具体实现，其设计理念围绕三个核心原则：

1. Markdown 优先 - 所有内容操作以 Markdown 格式作为主要输入输出，降低 AI Agent 的理解成本
2. 复合工具聚合 - 将 Notion 的原子 API 操作封装为 10 个复合工具（mega-tools），每个工具支持多个动作
3. 双模式传输 - 支持 stdio 和 HTTP 两种传输协议，适配不同的部署场景

资料来源：README.md

版本与发布

当前稳定版本为 v2.34.3（2026-05-29），通过 semver 语义化版本管理，采用 beta 版本进行迭代测试。社区维护的依赖更新通过 Renovate 自动化机器人管理（参见 Dependency Dashboard Issue #138）。

资料来源：server.json:5

MCP 质量评级

该服务器在 Agent Tool Intel 自动化质量分析中获得 Grade A 评级，表明其符合 MCP 协议最佳实践，具有良好的工具描述、输入模式定义和安全性保障。

技术架构

项目结构

better-notion-mcp/
├── src/
│   ├── init-server.ts         # 服务器入口，环境变量验证
│   ├── credential-state.ts    # 凭证状态机 + stdio 回退机制
│   ├── relay-schema.ts        # 中继表单模式（OAuth 令牌字段）
│   ├── tools/
│   │   ├── registry.ts        # 工具注册与路由
│   │   ├── composite/         # 领域化复合工具实现
│   │   │   ├── pages.ts       # 页面 CRUD 工具
│   │   │   ├── databases.ts   # 数据库工具
│   │   │   ├── blocks.ts      # 块级操作工具
│   │   │   ├── users.ts       # 用户查询工具
│   │   │   ├── workspace.ts   # 工作区信息工具
│   │   │   ├── comments.ts    # 评论管理工具
│   │   │   ├── content.ts     # 内容格式转换工具
│   │   │   └── file_uploads.ts # 文件上传工具
│   │   └── helpers/
│   │       ├── errors.ts      # 统一错误处理
│   │       ├── markdown.ts    # Markdown ↔ Notion Blocks 转换
│   │       ├── richtext.ts    # 富文本构造工具
│   │       ├── pagination.ts  # 分页与深度子内容处理
│   │       ├── properties.ts # 属性类型转换
│   │       ├── covers.ts      # 封面格式化
│   │       ├── icons.ts       # 图标格式化
│   │       └── security.ts    # URL 安全校验
│   ├── auth/                  # OAuth 2.1 + PKCE + DCR + Session
│   ├── transports/            # stdio + HTTP 传输层
│   └── docs/                  # Markdown 文档（MCP 资源）
├── scripts/                   # 构建脚本
├── tests/                     # 测试文件（与源码共置）
└── skills/                    # AI Agent 使用指南

资料来源：CLAUDE.md

复合工具体系

项目定义了 10 个复合工具，覆盖 Notion API 的主要功能领域：

每个工具通过 action 参数区分具体操作，支持链式参数依赖（某些参数在特定 action 下变为可选）。

资料来源：src/tools/registry.ts

凭证状态机

凭证管理采用三状态有限状态机：

graph TD
    A[awaiting_setup] -->|用户配置| B[setup_in_progress]
    B -->|配置完成| C[configured]
    C -->|配置失效| A
    B -->|配置失败| A

状态转移逻辑位于 credential-state.ts，stdio 模式下支持在 127.0.0.1 随机端口启动本地服务器进行 OAuth 流转。

资料来源：CLAUDE.md

传输层架构

graph LR
    A[AI Agent] -->|stdio| B[MCP SDK Direct]
    A -->|HTTP| C[MCP SDK HTTP Client]
    B --> D[Server Implementation]
    C --> D
    D --> E[Notion API]

当前默认使用 stdio 模式（MCP SDK direct routing），该架构简化了进程间通信复杂度。

资料来源：CLAUDE.md

核心模块详解

Markdown 转换引擎

src/tools/helpers/markdown.ts 实现了 Markdown 与 Notion Block JSON 的双向转换：

支持的 Markdown 语法：

RichText 注解支持：

• bold / italic / strikethrough / underline / code
• color（支持 default、gray、brown、orange、yellow、green、blue、purple、pink、red）

资料来源：src/tools/helpers/markdown.ts:1-20

富文本工具库

src/tools/helpers/richtext.ts 提供类型化的富文本构造函数：

text(content: string)           // 普通文本
bold(content: string)           // 加粗
italic(content: string)         // 斜体
strikethrough(content: string)  // 删除线
underline(content: string)      // 下划线
code(content: string)            // 内联代码

每个函数返回标准化的 RichTextItem 对象，确保与 Notion API 的兼容性。

资料来源：src/tools/helpers/richtext.ts

页面工具 (pages)

页面工具是使用频率最高的工具，支持完整的页面生命周期管理：

interface GetPageResult {
  page_id: string
  url: string
  created_time: string
  last_edited_time: string
  archived: boolean
  icon: any
  cover: any
  properties: Record<string, any>
  content: string          // Markdown 格式
  block_count: number
}

属性格式约定：

• 简单值自动转换：字符串 → title/rich_text，数字 → number，布尔 → checkbox
• 数组类型使用 multi_select
• 日期使用 ISO 格式（如 "2025-06-01"）

资料来源：src/tools/composite/pages.ts:29-40

部署与配置

环境变量

分发方式

项目支持两种分发渠道：

1. npm - @n24q02m/better-notion-mcp，通过 npx 运行
2. OCI (Docker) - docker.io/n24q02m/better-notion-mcp:latest

资料来源：server.json:10-35

开发环境

使用 mise 管理的运行时版本约束：

资料来源：renovate.json

安全性特性

URL 安全校验

内置 isSafeUrl() 函数防护以下危险协议：

• javascript: 伪协议
• 其他非 HTTP(S) 的 URL schemes

不安全链接会被解析器静默降级为纯文本或段落块，防止 XSS 攻击。

资料来源：src/tools/helpers/markdown.security.test.ts

头部信息脱敏

响应中的敏感 HTTP 头部会被不区分大小写地过滤，防止凭证泄露。

资料来源：社区 Issue #713

开发指南

常用命令

bun install          # 安装依赖
bun run build        # TypeScript 编译 + esbuild 打包
bun run check        # Biome 检查 + tsc 类型检查（CI 命令）
bun run check:fix    # 自动修复格式问题
bun test             # 运行测试

提交规范

采用 Conventional Commits 格式：type(scope): message，通过 git hooks 强制执行。

预提交检查

1. biome check --write - 格式化和 lint
2. tsc --noEmit - 类型检查
3. bun test - 单元测试

资料来源：AGENTS.md

与同类项目的关系

该项目是 n24q02m 组织下 MCP 服务器生态的一部分，关联项目包括：

所有项目共享统一的文档门户：mcp.n24q02m.com

资料来源：README.md

依赖管理

项目核心依赖 @n24q02m/mcp-core（内部 MCP 核心库），通过 Renovate 进行自动化版本管理。当前跟踪的版本包括 v1.15.0、v1.17.0、v1.17.1 等。

依赖更新会通过 Issue 自动通知维护者，执行 bun install 即可完成锁文件更新。

资料来源：社区 Issue #726, #769

概述

版本更新日志（CHANGELOG）是 better-notion-mcp 项目的核心文档，记录了每个发布版本的所有变更内容。该项目采用语义化版本号（SemVer）和 beta 版本并行发布的策略，确保用户能够了解稳定版的最新变化，同时开发者也能获取最新的测试功能。

当前最新稳定版本为 v2.34.3，发布于 2026-05-29。资料来源：server.json:3

版本号规范

语义化版本结构

better-notion-mcp 采用标准的语义化版本格式：

主版本号.次版本号.修订号[-预发布标签]

资料来源：server.json:5

预发布版本策略

项目采用 beta 版本迭代模式：

graph LR
    A[v2.31.0-beta.2] --> B[v2.31.0-beta.3]
    B --> C[v2.31.0-beta.5]
    C --> D[v2.31.0-beta.6]
    D --> E[v2.31.0]
    E --> F[v2.32.0-beta.1]
    F --> G[...最终稳定版]

更新日志结构

发布条目格式

每个发布版本包含以下标准字段：

版本链接

每个发布版本包含指向详细变更的链接：

**详细变更**: [v2.31.0-beta.6...v2.31.0](https://github.com/n24q02m/better-notion-mcp/compare/v2.31.0-beta.6...v2.31.0)

更新工作流

依赖更新流程

项目使用 Renovate 进行自动化依赖管理：

graph TD
    A[依赖检测] --> B[创建更新 Issue]
    B --> C{是否为核心依赖}
    C -->|mcp-core| D[优先级提升]
    C -->|其他依赖| E[标准流程]
    D --> F[生成 PR]
    E --> F
    F --> G[代码审查]
    G --> H[自动合并]
    H --> I[锁定文件更新]

依赖版本策略

项目维护严格的依赖版本控制策略，资料来源：renovate.json:1-50

mcp-core 更新流程

mcp-core 是项目的核心依赖，其更新流程如下：

1. 在 GitHub Releases 发布新版本（如 v1.17.1）
2. 自动生成更新 Issue（如 #769）
3. 手动更新 package.json 中的版本号
4. 执行 bun install 更新锁文件
5. 生成提交并发布新版本

近期版本历史

v2.34 系列

v2.31 系列

架构演进

v2.31 系列标志着重要的架构变更：

• stdio-pure 架构：移除了复杂的网络依赖，采用纯 stdio 传输模式
• MCP SDK 集成：直接使用 MCP SDK 进行路由和传输
• 多目标支持：支持同时连接多个 Notion 工作区

资料来源：AGENTS.md:1-30

提交规范

项目使用 Conventional Commits 规范，确保提交历史清晰可追溯：

示例：fix(pages): resolve property extraction edge case

预提交检查

每次提交前必须通过以下检查：

1. biome check --write - 代码格式化和 lint
2. tsc --noEmit - TypeScript 类型检查
3. bun run test - 运行测试套件

资料来源：AGENTS.md:35-45

社区参与

版本评级

better-notion-mcp 在 Agent Tool Intel 评级中获得 Grade A，表明项目质量达到高标准。资料来源：#772

依赖仪表板

项目维护依赖更新仪表板，追踪所有依赖的健康状态：资料来源：#138

相关资源

概述

better-notion-mcp 是一个 TypeScript 编写的 Markdown 优先的 MCP (Model Context Protocol) 服务器，用于为 AI 代理提供 Notion API 的完整访问能力。该项目采用复合工具 (composite tools) 设计模式，将多个相关操作整合为单一工具接口，显著降低了 AI 代理与 Notion API 交互的复杂性。

当前版本：v2.34.3，支持双模式运行（stdio 和 http），提供 10 个复合工具和 39+ 操作动作。资料来源：server.json:3

核心架构设计

架构分层

┌─────────────────────────────────────────────────────────────┐
│                    MCP Protocol Layer                        │
│              (mcp-core 统一抽象)                              │
├─────────────────────────────────────────────────────────────┤
│                    Transport Layer                           │
│         stdio Transport  │  http Transport                   │
├─────────────────────────────────────────────────────────────┤
│                    Server Core                               │
│   credential-state.ts  │  init-server.ts  │  relay-schema.ts │
├─────────────────────────────────────────────────────────────┤
│                    Tool Registry                            │
│                  src/tools/registry.ts                       │
├─────────────────────────────────────────────────────────────┤
│                 Composite Tools                             │
│  pages │ databases │ blocks │ users │ workspace │ comments  │
│  content_convert │ file_uploads │ setup │ help                  │
├─────────────────────────────────────────────────────────────┤
│                    Helpers                                   │
│  errors │ markdown │ richtext │ pagination │ properties │ security │
├─────────────────────────────────────────────────────────────┤
│                   Notion SDK                                 │
│              @notionhq/client                                │
└─────────────────────────────────────────────────────────────┘

项目目录结构

better-notion-mcp/
├── src/
│   ├── init-server.ts           # 服务器入口，环境验证
│   ├── credential-state.ts       # 凭证状态机 + stdio fallback
│   ├── relay-schema.ts           # Relay 表单模式
│   ├── tools/
│   │   ├── registry.ts           # 工具注册与路由分发
│   │   ├── composite/             # 复合工具实现
│   │   │   ├── pages.ts           # 页面 CRUD 操作
│   │   │   ├── databases.ts       # 数据库操作
│   │   │   ├── blocks.ts          # 块级操作
│   │   │   ├── comments.ts        # 评论操作
│   │   │   ├── users.ts           # 用户查询
│   │   │   ├── workspace.ts       # 工作区信息
│   │   │   ├── content.ts         # 内容格式转换
│   │   │   ├── file_uploads.ts    # 文件上传
│   │   │   ├── setup.ts           # 设置引导
│   │   │   └── help.ts            # 帮助文档
│   │   └── helpers/
│   │       ├── errors.ts          # 统一错误处理
│   │       ├── markdown.ts        # Markdown ↔ Blocks 转换
│   │       ├── richtext.ts        # 富文本构建
│   │       ├── pagination.ts      # 分页处理
│   │       ├── properties.ts      # 属性转换
│   │       ├── covers.ts          # 封面格式化
│   │       ├── icons.ts           # 图标格式化
│   │       └── security.ts        # 安全检查
│   ├── auth/                      # OAuth 2.1 + PKCE 实现
│   ├── transports/                # 传输层实现
│   └── docs/                      # MCP 资源文档
├── server.json                    # MCP 服务器元数据
└── AGENTS.md                      # 代理文档

凭证状态机

凭证管理是系统的核心组件之一，采用有限状态机 (FSM) 模式管理认证流程。

状态定义

资料来源：src/credential-state.ts:1-20

状态流转图

graph TD
    A[awaiting_setup] -->|用户提交 NOTION_TOKEN| B[setup_in_progress]
    B -->|验证成功| C[configured]
    B -->|验证失败| A
    C -->|需要重新配置| A
    C -->|MCP 请求| D[服务正常响应]

Stdio Fallback 机制

当使用 stdio 传输模式时，系统支持自动 spawn 本地服务器：

// credential-state.ts 中的关键逻辑
runLocalServer on 127.0.0.1:random

资料来源：src/credential-state.ts:15

工具注册与路由

工具注册表

所有 MCP 工具通过 registry.ts 统一注册和管理。每个工具包含：

• name: 工具唯一标识
• description: 工具描述（含支持的 actions 列表）
• annotations: 元数据提示（readOnlyHint, destructiveHint 等）
• inputSchema: JSON Schema 格式的输入参数定义

资料来源：src/tools/registry.ts:1-50

10 个复合工具一览

资料来源：src/tools/registry.ts:50-200

路由分发机制

graph LR
    A[MCP Request] --> B[registry.ts]
    B --> C{action 参数解析}
    C -->|pages| D[composite/pages.ts]
    C -->|databases| E[composite/databases.ts]
    C -->|blocks| F[composite/blocks.ts]
    C -->|其他| G[对应 composite 模块]
    D --> H[withErrorHandling 包装]
    H --> I[返回统一结果格式]

核心模块详解

错误处理系统

采用统一的错误处理模式：

export class NotionMCPError extends Error {
  constructor(
    message: string,    // 用户友好的错误信息
    code: string,       // 错误代码
    hint: string        // 修复建议
  )
}

// 包装函数
export function withErrorHandling<T>(fn: () => Promise<T>): Promise<T>

资料来源：src/tools/helpers/errors.ts:1-30

Markdown 转换引擎

支持 Notion Block 与 Markdown 之间的双向转换：

// 主要接口
markdownToBlocks(markdown: string): NotionBlock[]
blocksToMarkdown(blocks: NotionBlock[]): string

支持的 Markdown 语法：

| 折叠 | `

传输模式详解

better-notion-mcp 支持两种传输模式：本地 stdio 模式和远程 HTTP 模式。这两种模式决定了 MCP 服务器与客户端之间的通信方式，适用于不同的部署场景。

传输模式概述

stdio 模式

stdio 模式是传统的 MCP 传输方式，服务器通过标准输入/输出流与客户端通信。

工作原理

graph LR
    A[MCP Client] -->|stdio| B[better-notion-mcp]
    B -->|stdout| A
    C[环境变量] -->|NOTION_TOKEN| B

配置要求

stdio 模式需要配置 NOTION_TOKEN 环境变量：

export NOTION_TOKEN="secret_xxxxxxxxxxxx"
npx @n24q02m/better-notion-mcp

凭证状态机

stdio 模式使用三状态凭证机管理认证流程：

graph TD
    A[awaiting_setup] -->|检测到 NOTION_TOKEN| C[configured]
    B[setup_in_progress] -->|setup 完成| C
    C -->|启动本地服务器| D[runLocalServer on 127.0.0.1:random]

状态定义位于 src/credential-state.ts：

• awaiting_setup：等待初始配置
• setup_in_progress：配置进行中
• configured：已配置，准备运行

当配置完成后，服务器在 127.0.0.1:随机端口 启动本地服务器作为 fallback。

HTTP 模式

HTTP 模式支持远程部署，使用 OAuth 2.1 协议进行认证，无需在客户端存储 token。

OAuth 2.1 认证流程

sequenceDiagram
    participant C as MCP Client
    participant S as MCP Server
    participant N as Notion API
    
    C->>S: 请求访问
    S->>C: 重定向到 Notion OAuth
    C->>N: 授权请求
    N->>C: 返回 Authorization Code
    C->>S: 交换 Code
    S->>N: 获取 Access Token
    N->>S: 返回 Token
    S->>C: 建立会话

PKCE 安全机制

HTTP 模式实现 OAuth 2.1 的 PKCE（Proof Key for Code Exchange）扩展：

• code_verifier：随机生成的挑战码
• code_challenge：基于 verifier 的 SHA-256 哈希值
• 防止授权码被拦截后滥用

中继表单模式

服务器提供 /login 路由用于 OAuth 认证：

// 资料来源：src/relay-schema.ts:1-20
// 表单包含 Notion token 字段，支持 OAuth 流程

表单 Schema 定义了认证所需字段，包括：

• Notion token 输入字段
• OAuth 回调处理
• 会话管理

Docker 部署配置

HTTP 模式 Docker Compose

# 资料来源：docker-compose.http.yml
services:
  better-notion-mcp:
    image: docker.io/n24q02m/better-notion-mcp:latest
    environment:
      - NOTION_TOKEN=${NOTION_TOKEN}
      - PORT=3000
    ports:
      - "3000:3000"

环境变量

工具注册与路由

服务器初始化时根据传输模式注册工具：

// 资料来源：src/tools/registry.ts:1-30
const TOOLS = [
  {
    name: 'pages',
    description: 'Page CRUD for individual pages and database rows...',
    annotations: {
      title: 'Pages',
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: false,
      openWorldHint: false
    }
  },
  // ... 其他工具
]

工具列表

架构演进

stdio-pure 到 Dual Transport

v2.31.0-beta.3 标志着架构从纯 stdio 模式演进为双传输支持：

graph TD
    A[v2.30.x] -->|架构重构| B[v2.31.0+]
    B --> C[stdio 模式]
    B --> D[HTTP 模式]
    C -->|MCP SDK Direct| E[标准输入输出]
    D -->|OAuth 2.1| F[远程访问]

关键变更：

• 添加 src/transports/ 目录处理 stdio 和 http 传输
• 引入 OAuth 2.1 认证机制
• 实现 PKCE 安全扩展

版本兼容性

安全考量

Token 处理

• stdio 模式：token 通过环境变量传递，不记录日志
• HTTP 模式：使用短期 access token，定期刷新

网络安全

• HTTP 服务默认绑定 127.0.0.1
• Docker 部署需配置网络策略
• 支持 HTTPS 反向代理

快速开始

选择传输模式

graph TD
    A[开始] --> B{部署场景?}
    B -->|本地开发| C[stdio 模式]
    B -->|远程/多用户| D[HTTP 模式]
    C --> E[配置 NOTION_TOKEN]
    D --> F[设置 OAuth 应用]

常用命令

# stdio 模式
export NOTION_TOKEN="secret_xxx"
bun run start

# HTTP 模式 (Docker)
docker-compose -f docker-compose.http.yml up

# HTTP 模式 (源码)
bun run build
PORT=3000 ./dist/cli.js

故障排除

相关文档

• 官方文档
• OAuth 配置指南
• Docker 部署说明

概述

复合工具（Composite Tools）是 better-notion-mcp 的核心设计理念。该项目将 Notion API 的多个原子端点聚合为单一工具调用，实现"一次调用，多端协作"的模式，大幅减少 AI Agent 与 API 的交互次数。

核心价值

工具清单

当前版本共提供 10 个复合工具，涵盖 44 个操作动作：

环境要求

资料来源：package.json:engine

环境变量配置

必需环境变量

获取方式：访问 Notion My Integrations 创建新的集成并获取令牌。

# 设置环境变量
export NOTION_TOKEN="secret_xxxxxxxxxxxx"

资料来源：server.json:环境变量定义

服务启动配置

服务器支持两种启动模式：

认证方式

Better Notion MCP 支持两种认证流程：

方式一：令牌认证（stdio 模式）

适用于本地 AI 代理或 CLI 工具：

1. 在 Notion 创建集成并获取 secret_xxx 格式的令牌
2. 设置 NOTION_TOKEN 环境变量
3. 启动服务器即可使用所有工具

# 启动 stdio 模式
better-notion-mcp

方式二：OAuth 2.1 认证（HTTP 模式）

适用于远程部署和多用户场景：

• 支持 PKCE（Proof Key for Code Exchange）
• 支持 DCR（Dynamic Client Registration）
• 支持会话管理

资料来源：CLAUDE.md:OAuth 2.1 + PKCE

凭证状态机

服务器内部维护凭证状态，决定如何处理请求：

graph TD
    A[启动] --> B{检查凭证}
    B -->|无配置| C[awaiting_setup]
    B -->|配置不完整| D[setup_in_progress]
    B -->|配置完成| E[configured]
    C -->|用户完成设置| E
    D -->|用户完成设置| E
    E --> F[处理请求]

对于 stdio 模式，服务器会在 127.0.0.1:随机端口 启动本地服务器作为备用方案。

资料来源：CLAUDE.md:状态机

中继配置

服务器支持通过中继（Relay）服务转发请求，适用于需要代理的场景：

// 中继表单 schema
{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "title": "Notion Token",
      "description": "secret_xxx 或 oauth_access_token"
    }
  },
  required": ["token"]
}

中继服务可接收两种格式的令牌：

• secret_xxx - 直接集成令牌
• oauth_access_token - OAuth 访问令牌

资料来源：src/relay-schema.ts

双传输模式架构

graph LR
    subgraph "本地模式"
        A1[AI Agent] -->|stdio| B1[better-notion-mcp]
    end
    
    subgraph "远程模式"
        A2[远程客户端] -->|HTTP| B2[MCP Relay]
        B2 -->|转发| B3[better-notion-mcp]
    end
    
    B1 -->|API| C[Notion API]
    B3 -->|API| C

stdio 模式配置

# 直接运行
better-notion-mcp

# 或通过 Docker
docker run --rm -i -e NOTION_TOKEN n24q02m/better-notion-mcp:latest

资料来源：README.md:双传输

HTTP 模式配置

远程 HTTP 传输使用 OAuth 2.1，无需在服务器端存储令牌：

1. 配置 OAuth 应用
2. 客户端通过授权流程获取访问令牌
3. 请求通过 HTTPS 转发到 MCP 服务器

安全配置

令牌安全

• NOTION_TOKEN 应始终保密，不提交到版本控制
• 使用环境变量或密钥管理服务存储
• 中继传输时，令牌仅在建立连接时使用

URL 安全验证

服务器内置 isSafeUrl 检查，防止 XSS 攻击：

// 安全检查包括
// - javascript: 协议拦截
// - data: URL 限制
// - 外部链接验证

资料来源：src/tools/helpers/markdown.ts:isSafeUrl

快速开始配置

步骤 1：安装服务器

# 通过 npm
npx @n24q02m/better-notion-mcp

# 或从源码构建
git clone https://github.com/n24q02m/better-notion-mcp.git
cd better-notion-mcp
bun install
bun run build

步骤 2：创建 Notion 集成

1. 访问 Notion My Integrations
2. 点击 "New integration"
3. 填写名称和关联工作区
4. 复制生成的令牌

步骤 3：配置环境变量

export NOTION_TOKEN="secret_xxxxxxxxxxxxxxxxxxxx"

步骤 4：授权访问

将集成连接到需要访问的 Notion 页面或数据库：

1. 打开 Notion 页面
2. 点击右上角 ... 菜单
3. 选择 "Connections" → 添加你的集成

步骤 5：验证配置

# 运行检查命令
bun run check

# 运行测试
bun run test

高级配置选项

开发环境配置

# 安装依赖
bun install

# 代码检查
bun run check

# 自动修复
bun run check:fix

# 运行测试
bun run test

资料来源：CLAUDE.md:常用命令

Docker 配置

# 构建镜像
bun run docker:build

# 运行容器
bun run docker:run

# 推送镜像
bun run docker:push

常见配置问题

问题 1：凭证状态为 awaiting_setup

原因：NOTION_TOKEN 未设置或格式不正确

解决：

# 确认环境变量已设置
echo $NOTION_TOKEN

# 验证令牌格式（应为 secret_xxx）

问题 2：OAuth 授权失败

原因：

• OAuth 应用配置不正确
• PKCE 验证失败
• 重定向 URI 不匹配

解决：检查 OAuth 应用设置中的客户端 ID、密钥和重定向 URI

问题 3：权限不足

原因：集成未添加到 Notion 页面或数据库

解决：

1. 打开 Notion 页面
2. 点击 ... → "Connections"
3. 添加对应的集成

工具配置矩阵

资料来源：README.md:工具

版本信息

当前最新版本：v2.34.3

该版本已修复 mcp-core 1.17.1 中的 BearerMCPApp resource_metadata 问题。

如需更新配置依赖：

# TypeScript
bun install

# 更新 mcp-core 后重新构建
bun run build

延伸阅读

• 架构文档 - 深入了解代码架构
• 贡献指南 - 开发流程和提交规范
• 安全模型 - 信任模型和隐私说明

部署模式概述

better-notion-mcp 支持两种传输模式：

资料来源：README.md:40-42

graph LR
    A[better-notion-mcp] --> B{传输模式}
    B --> C[stdio 模式<br/>本地 Token 认证]
    B --> D[HTTP 模式<br/>OAuth 2.1 认证]
    
    C --> E[直接进程通信]
    D --> F[MCP SDK Direct]
    D --> G[中继服务器]

前置要求

环境依赖

资料来源：renovate.json:14-22

Notion 集成准备

1. 访问 Notion Integrations 创建集成
2. 获取集成令牌 (Integration Token)
3. 将集成连接到目标 Notion 工作区

方式一：npm/npx 快速部署

标准安装

通过 npm 全局安装或直接使用 npx 运行：

# 使用 npx 直接运行（推荐）
npx @n24q02m/better-notion-mcp

# 或全局安装
npm install -g @n24q02m/better-notion-mcp

资料来源：server.json:11-17

环境变量配置

# stdio 模式必需
NOTION_TOKEN=secret_xxxxxxxxxxxx

# HTTP 模式可选
NOTION_CLIENT_ID=your_oauth_client_id
NOTION_CLIENT_SECRET=your_oauth_client_secret
REDIRECT_URI=http://localhost:3000/callback

方式二：Docker 部署

stdio 模式

适用于本地开发环境，使用 Notion Token 直接认证：

FROM oven/bun:1-alpine
WORKDIR /app
COPY . .
RUN bun install --frozen-lockfile
RUN bun run build
ENTRYPOINT ["bun", "dist/index.js"]

资料来源：Dockerfile

#### 运行命令

docker run -it \
  -e NOTION_TOKEN=secret_xxxxxxxxxxxx \
  n24q02m/better-notion-mcp:latest

HTTP 模式

适用于远程服务部署，支持 OAuth 2.1 认证：

services:
  notion-mcp:
    image: n24q02m/better-notion-mcp:latest
    ports:
      - "3000:3000"
    environment:
      - NOTION_CLIENT_ID=${NOTION_CLIENT_ID}
      - NOTION_CLIENT_SECRET=${NOTION_CLIENT_SECRET}
      - REDIRECT_URI=http://localhost:3000/callback
      - MCP_SERVER_PORT=3000
    restart: unless-stopped

资料来源：docker-compose.http.yml

#### 启动服务

# 启动 HTTP 服务
docker-compose -f docker-compose.http.yml up -d

# 查看日志
docker-compose -f docker-compose.http.yml logs -f

方式三：源码构建部署

克隆项目

git clone https://github.com/n24q02m/better-notion-mcp.git
cd better-notion-mcp

安装依赖

bun install

资料来源：CLAUDE.md:12

构建

bun run build

构建命令说明：

• tsc --build - TypeScript 编译
• esbuild - CLI bundle 打包

资料来源：CLAUDE.md:13-15

运行检查

# 运行检查（lint + 类型检查 + 测试）
bun run check

# 自动修复格式问题
bun run check:fix

资料来源：CLAUDE.md:16-18

本地运行

# 设置环境变量
export NOTION_TOKEN=secret_xxxxxxxxxxxx

# 运行服务器
bun run start

MCP 服务器配置

server.json 配置说明

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.n24q02m/better-notion-mcp",
  "description": "Markdown-first MCP server for Notion API with 9 composite tools and 39+ actions.",
  "version": "2.34.3",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@n24q02m/better-notion-mcp",
      "version": "2.34.3",
      "runtimeHint": "npx",
      "transport": {
        "type": "stdio"
      },
      "environmentVariables": [
        {
          "description": "Notion integration token. Create at https://www.notion.so/my-integrations",
          "isRequired": true,
          "isSecret": true,
          "name": "NOTION_TOKEN"
        }
      ]
    },
    {
      "registryType": "oci",
      "identifier": "docker.io/n24q02m/better-notion-mcp:latest",
      "runtimeHint": "docker",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

资料来源：server.json:1-36

MCP 客户端配置示例

#### Claude Desktop 配置

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["@n24q02m/better-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "secret_xxxxxxxxxxxx"
      }
    }
  }
}

#### Docker 模式配置

{
  "mcpServers": {
    "notion": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "NOTION_TOKEN=secret_xxxxxxxxxxxx", "n24q02m/better-notion-mcp:latest"]
    }
  }
}

OAuth 2.1 认证流程 (HTTP 模式)

sequenceDiagram
    participant U as 用户
    participant C as MCP 客户端
    participant S as MCP 服务器
    participant N as Notion API
    
    C->>S: 请求访问
    S->>U: 重定向到 Notion 授权页
    U->>N: 授权登录
    N->>U: 授权确认
    N-->>S: 返回授权码 (code)
    S->>N: 交换 token (PKCE)
    N-->>S: 返回 access_token
    S->>N: 调用 Notion API
    N-->>S: 返回数据
    S-->>C: 返回结果

OAuth 配置步骤

1. 在 Notion 开发者平台创建 OAuth 应用
2. 配置回调地址：http://localhost:3000/callback（开发环境）
3. 设置环境变量：

• NOTION_CLIENT_ID
• NOTION_CLIENT_SECRET
• REDIRECT_URI

安全注意事项

Token 安全

网络安全

• HTTP 模式建议配合反向代理 (Nginx) 使用 HTTPS
• 限制 REDIRECT_URI 到可信域名
• 定期轮换 OAuth 凭证

链接安全

项目实现了 URL 安全检查机制：

// javascript: 协议链接会被安全过滤
it('should sanitize javascript: links', () => {
  const result = parseRichText('[Click me](javascript:alert(1))')
  expect(result[0].text.link).toBeNull()
})

资料来源：src/tools/helpers/markdown.security.test.ts:7-14

故障排查

常见问题

调试模式

# 启用详细日志
DEBUG=* bun run start

# Docker 调试
docker run --rm -e DEBUG=* n24q02m/better-notion-mcp:latest

版本管理

项目使用 Renovate 进行依赖管理，版本更新会自动创建 Pull Request。

最新稳定版本：v2.34.3

资料来源：社区动态

相关文档

项目结构

better-notion-mcp/
├── src/
│   ├── init-server.ts          # 服务器入口，环境变量验证
│   ├── credential-state.ts     # 凭证状态机 + stdio 后备启动
│   ├── relay-schema.ts         # 中继表单架构（Notion Token 字段）
│   ├── auth/                    # OAuth 2.1 + PKCE、DCR、会话管理
│   ├── transports/              # stdio + http 传输处理
│   ├── docs/                    # 作为 MCP 资源服务的 Markdown 文档
│   └── tools/
│       ├── registry.ts         # 工具注册与路由
│       ├── composite/           # 每个域一个文件（pages、databases、blocks 等）
│       └── helpers/             # errors、markdown、richtext、pagination、properties
├── scripts/                     # 构建脚本
├── build/                       # 构建输出
├── tests/                       # 测试文件（与源文件同目录放置）
└── bin/                         # CLI 入口脚本

资料来源：CONTRIBUTING.md:1-20

核心组件说明

工具系统架构

项目采用组合式工具（Composite Tools）设计，将多个原子端点合并为单一工具调用：

资料来源：AGENTS.md:1-20

状态机管理

凭证状态管理使用三态状态机：

graph TD
    A[awaiting_setup] -->|setup 完成| B[configured]
    A -->|启动配置流程| C[setup_in_progress]
    C -->|配置成功| B
    C -->|配置失败| A
    B -->|需要重新配置| A

• awaiting_setup：初始状态，等待用户配置
• setup_in_progress：配置进行中
• configured：配置完成，可正常操作

资料来源：CLAUDE.md:1-15

开发环境配置

环境要求

资料来源：renovate.json:1-50

依赖安装

bun install

使用 bun 作为包管理器和运行时。

资料来源：CLAUDE.md:20-25

常用开发命令

资料来源：CLAUDE.md:20-35

Docker 相关命令

bun run docker:build    # 构建 Docker 镜像
bun run docker:push     # 推送镜像到仓库
bun run docker:run      # 运行容器（需要 NOTION_TOKEN 环境变量）

资料来源：package.json:1-50

代码规范

Biome 配置

项目使用 Biome 进行代码检查和格式化，配置文件位于根目录：

• 包含 lint 规则和格式化选项
• 自动应用，无需手动配置

资料来源：CONTRIBUTING.md:30-50

Pre-commit 钩子

提交前自动执行以下检查：

1. biome check --write - Lint + 格式化
2. tsc --noEmit - 类型检查
3. bun run test - 运行测试

资料来源：AGENTS.md:40-50

测试规范

测试文件位置

测试文件与源文件同目录放置：

src/tools/helpers/
├── markdown.ts
├── markdown.test.ts        # 测试文件
├── richtext.ts
└── richtext.test.ts

资料来源：AGENTS.md:25-30

测试配置

使用 Vitest 作为测试框架：

// vitest.config.ts
import { defineConfig } from 'vitest/config'

资料来源：AGENTS.md:30-40

安全测试

markdown.security.test.ts 文件包含 XSS 和恶意链接防护测试：

describe('Security: Markdown Parsing Vulnerabilities', () => {
  it('should sanitize javascript: links in rich text', () => {
    // 验证 javascript: 协议链接被正确过滤
  })
})

资料来源：src/tools/helpers/markdown.security.test.ts:1-20

提交规范

提交信息格式

项目使用 Conventional Commits 规范：

<type>(<scope>): <message>

类型说明：

资料来源：AGENTS.md:45-55

依赖管理

Renovate 配置

项目使用 Renovate 自动管理依赖更新：

资料来源：renovate.json:1-60

手动更新 mcp-core

当 mcp-core 发布新版本时，需要手动执行以下操作：

# TypeScript 端
1. 更新 package.json 中的 @n24q02m/mcp-core 版本
2. 运行 bun install 更新锁文件

# Python 端（如需要）
1. 更新 pyproject.toml 中的 n24q02m-mcp-core 版本
2. 重新生成锁文件

资料来源：社区 Issue #769

工具注册与路由

工具注册流程

所有工具在 registry.ts 中注册：

{
  name: 'content_convert',
  description: 'Convert between markdown and Notion block JSON...',
  annotations: {
    title: 'Content Convert',
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: false
  },
  inputSchema: {
    type: 'object',
    properties: {
      direction: {
        type: 'string',
        enum: ['markdown-to-blocks', 'blocks-to-markdown']
      },
      content: { type: 'string' }
    },
    required: ['direction', 'content']
  }
}

资料来源：src/tools/registry.ts:1-50

工具注解说明

文档编写规范

JSDoc 注释

• 每个函数添加 /** */ JSDoc 注释
• 引用 Notion API 端点
• 不使用 @param/@returns 标签，依赖 TypeScript 类型

资料来源：AGENTS.md:35-45

文件级注释

每个模块顶部添加块注释描述模块用途：

/**
 * Rich Text Utilities
 * Helpers for working with Notion's rich text format
 */

资料来源：src/tools/helpers/richtext.ts:1-10

贡献流程

1. Fork 仓库 并创建功能分支
2. 开发实现，遵循代码规范
3. 运行检查：bun run check
4. 提交代码，使用 Conventional Commits 格式
5. 创建 Pull Request，等待代码审查

资料来源：CONTRIBUTING.md:1-50

发布流程

版本号遵循语义化版本（SemVer）：

• 主版本号：不兼容的 API 变更
• 次版本号：向后兼容的功能新增
• 补丁版本号：向后兼容的问题修复

项目使用 python-semantic-release 进行自动版本管理和发布，通过 GitHub Actions 自动化流程执行。

资料来源：renovate.json:20-30

概述

better-notion-mcp 是一个 TypeScript 编写的 MCP (Model Context Protocol) 服务器，用于为 AI 代理提供 Notion API 的访问能力。项目采用 Markdown 优先的设计理念，将 Notion 的 JSON 块格式与人类可读的 Markdown 进行双向转换。 资料来源：AGENTS.md

当前版本为 v2.34.3，支持双传输模式（stdio 和 HTTP），并依赖 @n24q02m/mcp-core 核心包实现 MCP 协议。社区近期关注点集中在依赖更新（mcp-core v1.17.1）和测试覆盖增强。 资料来源：社区上下文 - v2.34.3

Pitfall Log / 踩坑日志

项目：n24q02m/better-notion-mcp

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：chore: bump @n24q02m/mcp-core to 1.17.0。

1. 安装坑 · 来源证据：chore: bump @n24q02m/mcp-core to 1.17.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore: bump @n24q02m/mcp-core to 1.17.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b0b34124b9c047ff9f1fe770e7a45276 | https://github.com/n24q02m/better-notion-mcp/issues/768 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：chore: bump @n24q02m/mcp-core to 1.17.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore: bump @n24q02m/mcp-core to 1.17.1
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9689093afc81461db714925d633f4320 | https://github.com/n24q02m/better-notion-mcp/issues/769 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | last_activity_observed missing

5. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | no_demo; severity=medium

7. 安全/权限坑 · 来源证据：Dependency Dashboard

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Dependency Dashboard
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_85c84b0ec750481aa04b968b66e815aa | https://github.com/n24q02m/better-notion-mcp/issues/138 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.n24q02m/better-notion-mcp:2.34.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.n24q02m%2Fbetter-notion-mcp/versions/2.34.3 | release_recency=unknown