项目概述

Notion MCP Server 是 Notion 官方提供的 MCP（Model Context Protocol）服务器，用于将 Notion API 作为 MCP 工具暴露给 AI 客户端使用。该项目通过自动生成的方式从 OpenAPI 规范创建 MCP 工具，无需手动编写工具代码。

核心特性：

• 自动从 OpenAPI 3.1.0 规范生成 MCP 工具
• 支持 stdio 和 Streamable HTTP 两种传输模式
• 使用 Notion API 版本 2025-09-03（Data Source Edition）
• 提供 22 个 MCP 工具（v2.0.0 版本）
• 支持 Cursor、Claude、Zed、GitHub Copilot CLI 等主流 MCP 客户端

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

概述

Notion MCP Server 是一个实现 MCP（Model Context Protocol）协议的服务器，用于将 Notion API 暴露为 MCP 工具供 AI 代理使用。该项目采用自动生成架构，通过 OpenAPI 规范定义所有工具，无需为每个 API 端点编写独立代码。

核心设计理念

整体架构

graph TD
    subgraph "数据源层"
        A["scripts/notion-openapi.json<br/>OpenAPI 3.1.0 规范"]
    end
    
    subgraph "核心处理层"
        B["init-server.ts<br/>服务器初始化"]
        C["parser.ts<br/>OpenAPI → MCP 转换器"]
        D["proxy.ts<br/>MCP 工具代理"]
    end
    
    subgraph "传输层"
        E["STDIO 传输"]
        F["HTTP/Streamable 传输"]
    end
    
    subgraph "外部调用"
        G["AI 客户端<br/>Cursor/Claude/Copilot"]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    D --> F
    E --> G
    F --> G
    
    style A fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#e8f5e9

模块详解

1. 入口模块 (scripts/start-server.ts)

服务器启动入口，负责命令行参数解析和传输协议选择。

#### 支持的参数

#### 环境变量

资料来源：scripts/start-server.ts:1-50

2. 服务器初始化 (src/init-server.ts)

负责加载 OpenAPI 规范、验证配置并创建 MCP 服务器实例。

#### 初始化流程

sequenceDiagram
    participant 启动脚本
    participant init-server
    participant MCPProxy
    participant OpenAPI规范
    
    启动脚本->>init-server: 加载 OpenAPI 规范
    init-server->>MCPProxy: 创建代理实例
    MCPProxy->>OpenAPI规范: 解析端点
    MCPProxy->>MCPProxy: 注册工具处理器
    init-server->>启动脚本: 返回服务器实例

资料来源：src/init-server.ts, src/openapi-mcp-server/mcp/proxy.ts:1-50

3. OpenAPI 解析器 (src/openapi-mcp-server/openapi/parser.ts)

核心转换模块，将 OpenAPI 3.1.0 规范转换为 MCP 工具定义。

#### 主要功能

• 解析 OpenAPI 路径和操作
• 转换 JSON Schema 参数定义
• 生成 MCP 工具的 inputSchema 和 returnSchema
• 支持多种输出格式：MCP、OpenAI ChatCompletion、Anthropic Tool

#### 转换方法

#### Schema 转换处理

// 处理类型映射关系
- OpenAPI binary → JSON Schema uri-reference
- object 类型 → 保留 properties 和 additionalProperties
- array 类型 → 递归转换 items
- oneOf/anyOf/allOf → 递归处理联合类型

资料来源：src/openapi-mcp-server/openapi/parser.ts:1-100

4. MCP 代理模块 (src/openapi-mcp-server/mcp/proxy.ts)

负责 MCP 工具的注册、路由和执行。

#### 核心组件

#### 工具命名规则

• 工具名称来源：operationId 字段
• 长度限制：截断至 64 字符
• 显示格式：Title Case（如 RetrieveADatabase）

#### 请求处理流程

graph LR
    A["MCP 调用请求"] --> B["解析工具名称"]
    B --> C["查找 OpenAPI 操作"]
    C --> D["提取参数"]
    D --> E["构造 HTTP 请求"]
    E --> F["发送请求到 Notion API"]
    F --> G["返回响应结果"]

#### 工具注解

资料来源：src/openapi-mcp-server/mcp/proxy.ts:50-150

5. HTTP 客户端 (src/openapi-mcp-server/client/http-client.ts)

负责执行实际的 API 调用。

#### 请求构造

// 参数分类处理
1. 路径参数 (path) → URL 路径占位符
2. 查询参数 (query) → URL 查询字符串
3. 请求体 (body) → JSON 请求体
4. 表单数据 (formData) → multipart/form-data

#### 认证头处理

默认从环境变量读取认证信息：

• OPENAPI_MCP_HEADERS：JSON 格式的完整请求头
• 自动注入 Authorization 和 Notion-Version

资料来源：src/openapi-mcp-server/client/http-client.ts:1-100

6. 认证模块 (src/openapi-mcp-server/auth/index.ts)

处理 HTTP 传输的 Bearer Token 认证。

#### 认证选项

#### 认证流程

graph TD
    A["HTTP 请求到达"] --> B{"检查 --disable-auth"}
    B -->|是| C["跳过认证"]
    B -->|否| D["提取 Authorization 头"]
    D --> E{"验证 Bearer Token"}
    E -->|通过| F["处理请求"]
    E -->|失败| G["返回 401 错误"]

资料来源：src/openapi-mcp-server/auth/index.ts

数据流架构

flowchart LR
    subgraph 用户层
        A["AI 客户端"]
        B["Notion Token"]
    end
    
    subgraph MCP服务器
        C["STDIO/HTTP 接收"]
        D["工具列表请求"]
        E["工具调用请求"]
        F["工具解析"]
        G["HTTP 执行器"]
    end
    
    subgraph Notion API
        H["Notion API v2025-09-03"]
    end
    
    A -->|MCP 协议| C
    B -->|认证| G
    C --> D
    C --> E
    E --> F
    F --> G
    G -->|HTTP/REST| H
    H -->|JSON 响应| G
    G -->|MCP 响应| A

传输协议

STDIO 模式

默认传输方式，适用于本地集成。

npx @notionhq/notion-mcp-server

HTTP/Streamable 模式

适用于远程部署和分布式架构。

npx @notionhq/notion-mcp-server --transport http --port 3000

扩展机制

添加新 API 端点

仅需修改 scripts/notion-openapi.json，工具将自动生成：

graph LR
    A["修改 notion-openapi.json"] --> B["添加/修改路径"]
    B --> C["定义 operationId"]
    C --> D["npm run build"]
    D --> E["工具自动可用"]

支持的工具格式

依赖关系图

graph TD
    package.json --> express
    package.json --> @modelcontextprotocol-sdk
    package.json --> openapi-types
    
    express --> src/init-server.ts
    @modelcontextprotocol-sdk --> src/openapi-mcp-server/mcp/proxy.ts
    
    src/init-server.ts --> src/openapi-mcp-server/mcp/proxy.ts
    src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/openapi/parser.ts
    src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/client/http-client.ts
    src/openapi-mcp-server/mcp/proxy.ts --> src/openapi-mcp-server/auth/index.ts
    
    src/openapi-mcp-server/openapi/parser.ts --> openapi-types
    scripts/start-server.ts --> src/init-server.ts

关键设计决策

1. 规范即代码

通过将 OpenAPI 规范作为唯一的工具定义来源，实现了：

• 单点维护
• 文档与实现同步
• 多格式工具自动导出

2. 分层架构

3. 认证安全

HTTP 传输强制使用 Bearer Token 认证，支持：

• 自动生成（开发模式）
• 环境变量配置（生产推荐）
• 命令行显式指定（最高优先级）

总结

Notion MCP Server 采用现代化的分层架构设计，通过 OpenAPI 规范驱动实现零手动维护的工具生成机制。核心模块各司其职：解析器负责格式转换、代理负责工具注册、HTTP 客户端负责实际请求执行、认证模块负责安全控制。这种设计既保证了代码的可维护性，又为未来扩展提供了良好的基础。

概述

MCP 工具集是 Notion MCP Server 的核心功能模块，它将 Notion OpenAPI 规范自动转换为 Model Context Protocol (MCP) 工具，使 AI 助手能够直接调用 Notion API 进行操作。

该系统的设计理念是仅需修改 OpenAPI 规范文件，即可自动生成对应的 MCP 工具，无需手动编写代码。工具的命名、参数定义、响应模式等全部从 OpenAPI 规范派生。

资料来源：CLAUDE.md

架构总览

核心数据流

graph TD
    A["scripts/notion-openapi.json<br/>OpenAPI 3.1.0 规范"] --> B["src/init-server.ts<br/>加载与验证规范"]
    B --> C["OpenAPIToMCPConverter<br/>openapi/parser.ts"]
    C --> D["MCPProxy<br/>mcp/proxy.ts"]
    D --> E["HTTP Client<br/>client/http-client.ts"]
    E --> F["Notion API<br/>api.notion.com"]
    
    C -.->|convertToMCPTools| G["MCP 工具定义"]
    C -.->|convertToOpenAITools| H["OpenAI 工具格式"]
    C -.->|convertToAnthropicTools| I["Anthropic 工具格式"]

关键组件

资料来源：CLAUDE.md

OpenAPI 到 MCP 工具转换机制

转换流程

sequenceDiagram
    participant OpenAPI as OpenAPI 规范
    participant Parser as OpenAPIToMCPConverter
    participant MCP as MCPProxy
    
    OpenAPI->>Parser: 加载规范文件
    Parser->>Parser: 解析 paths 和 operations
    Parser->>Parser: convertOperationToJsonSchema()
    Parser->>Parser: extractResponseType()
    Parser->>Parser: convertToMCPTools()
    Parser-->>MCP: { tools, openApiLookup, zip }

核心转换方法

OpenAPIToMCPConverter 类提供三种工具格式转换方法：

资料来源：src/openapi-mcp-server/openapi/parser.ts:120-180

#### 1. convertToMCPTools()

生成原生 MCP 工具定义，返回包含三个属性的对象：

{
  tools: Record<string, { methods: NewToolMethod[] }>,  // 按 API 名称分组的工具
  openApiLookup: Record<string, OpenAPIV3.OperationObject>,  // 操作查找表
  zip: Record<string, { openApi, mcp }>  // 配对的 OpenAPI 与 MCP 工具
}

资料来源：src/openapi-mcp-server/openapi/parser.ts:85-140

#### 2. convertToOpenAITools()

转换为 OpenAI ChatCompletion 工具格式：

{
  type: 'function',
  function: {
    name: operation.operationId,
    description: 描述文本,
    parameters: JSON Schema
  }
}

资料来源：src/openapi-mcp-server/openapi/parser.ts:143-165

#### 3. convertToAnthropicTools()

转换为 Anthropic Claude 工具格式：

{
  name: operation.operationId,
  description: 描述文本,
  input_schema: JSON Schema
}

资料来源：src/openapi-mcp-server/openapi/parser.ts:168-190

Schema 转换细节

#### 类型映射规则

资料来源：src/openapi-mcp-server/openapi/parser.ts:30-90

#### 复合类型处理

对于包含 oneOf、anyOf、allOf 的复杂 Schema，系统采用以下策略：

// 如果 schema 包含 oneOf/anyOf/allOf 或是数组
if ('anyOf' in schema || 'oneOf' in schema || 'allOf' in schema) {
  return { anyOf: [schema, { type: 'string' }] }
}

这确保了参数可以接受原始值或 JSON 字符串形式。

资料来源：src/openapi-mcp-server/openapi/parser.ts:260-280

#### 响应 Schema 提取

graph LR
    A["responses 对象"] --> B{"查找成功响应"}
    B -->|"200/201/202/204"| C["解析 content"]
    B -->|"无匹配"| D["返回 null"]
    C --> E{"application/json?"}
    E -->|是| F["转换 schema<br/>添加 $defs"]
    E -->|否| G["处理二进制格式"]

系统按优先级 200 → 201 → 202 → 204 查找成功响应，并从 application/json content 中提取响应 schema。

资料来源：src/openapi-mcp-server/openapi/parser.ts:290-320

工具命名规范

命名来源

工具名称直接取自 OpenAPI 规范的 operationId 字段：

{
  "operationId": "retrieve-a-database"
}

转换后生成工具名：Retrieve-A-Database

资料来源：CLAUDE.md

名称处理规则

工具注册与执行

MCPProxy 架构

classDiagram
    class MCPProxy {
        +mcpServer: Server
        +openApiSpec: OpenAPIV3.Document
        +openApiLookup: Record
        +setupHandlers() void
        +executeTool(name, args) Promise
    }
    
    class HTTPClient {
        +executeOperation(operationId, params) Promise
    }
    
    MCPProxy --> HTTPClient : 使用

参数反序列化机制

MCP 协议在传输过程中会将复杂参数序列化为字符串。deserializeParams() 函数负责反序列化：

function deserializeParams(params: Record<string, unknown>): Record<string, unknown>

处理逻辑：

1. 检测字符串值是否以 {/[ 开头并以 }/] 结尾
2. 尝试使用 JSON.parse() 解析
3. 对嵌套对象递归反序列化
4. 对数组中的 JSON 字符串项逐个处理

资料来源：src/openapi-mcp-server/mcp/proxy.ts:10-60

工具执行流程

sequenceDiagram
    participant Client as MCP 客户端
    participant Proxy as MCPProxy
    participant Deserializer as deserializeParams
    participant HTTP as HTTPClient
    participant API as Notion API
    
    Client->>Proxy: 调用工具 "retrieve-a-database"
    Proxy->>Deserializer: 反序列化参数
    Deserializer-->>Proxy: 处理后的参数对象
    Proxy->>HTTP: operationId + 参数
    HTTP->>API: GET /v1/databases/{database_id}
    API-->>HTTP: 200 OK + 数据库数据
    HTTP-->>Proxy: API 响应
    Proxy-->>Client: MCP 响应结果

HTTP 客户端实现

请求构建流程

HTTPClient 负责将工具调用转换为实际的 HTTP 请求：

资料来源：src/openapi-mcp-server/client/http-client.ts:1-50

请求体处理

// 根据是否有请求体设置 headers
const hasBody = Object.keys(bodyParams).length > 0
const headers = formData
  ? formData.getHeaders()
  : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }

// 调用格式：第一个参数为 URL 参数，第二个为 body 参数
const response = await operationFn(urlParameters, hasBody ? bodyParams : undefined, requestConfig)

资料来源：src/openapi-mcp-server/client/http-client.ts:50-80

服务器传输模式

支持的传输类型

资料来源：scripts/start-server.ts:20-40

命令行参数

环境变量配置

--auth-token 参数优先于 AUTH_TOKEN 环境变量。

资料来源：scripts/start-server.ts:60-100

API 版本支持

服务器使用 Notion API 版本 2025-09-03 (Data Source Edition)。

规范文件同时包含两类端点：

资料来源：CLAUDE.md

使用示例

工具调用示例

当用户发出以下指令时：

Add a page titled "Notion MCP" to page "Development"

AI 助手会自动规划并调用以下 API 操作：

1. v1/search - 查找名为 "Development" 的页面
2. v1/pages - 创建新页面

工具引用方式

工具支持以下引用方式：

测试框架

测试配置

测试文件位于源文件同级的 __tests__ 目录中，使用 Vitest 测试框架：

npm test              # 运行所有测试
npm run test:watch    # 监视模式
npm run test:coverage # 生成覆盖率报告

依赖包

资料来源：package.json

扩展机制

添加新端点

要添加新的 API 端点，只需修改 scripts/notion-openapi.json 文件，无需修改其他代码：

1. 在 paths 对象中添加新的端点定义
2. 设置唯一的 operationId
3. 定义 parameters 和 requestBody
4. 定义 response schema

系统会自动：

• 生成新的 MCP 工具定义
• 更新工具注册表
• 处理参数序列化和反序列化

资料来源：CLAUDE.md

自定义 Header 配置

对于需要自定义 headers 的高级用例，可通过 OPENAPI_MCP_HEADERS 环境变量传入：

{
  "Authorization": "Bearer ntn_****",
  "Notion-Version": "2025-09-03"
}

概述

Notion MCP Server 是官方提供的 Model Context Protocol (MCP) 服务器，用于将 Notion API 以 MCP 工具的形式暴露给 AI 客户端。项目采用 TypeScript 开发，支持两种传输模式（STDIO 和 Streamable HTTP）和多种认证方式。

核心依赖包括：

• @modelcontextprotocol/sdk (^1.25.1) - MCP 协议实现
• axios (^1.8.4) - HTTP 请求处理
• express (^4.21.2) - HTTP 传输层支持
• zod (3.24.1) - 参数验证

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

环境准备

前置条件

注意：Headers 类在 Node.js 18+ 才原生支持，较低版本使用 polyfill 实现。

资料来源：src/openapi-mcp-server/client/polyfill-headers.ts:1-10

Notion 集成配置

1. 访问 Notion 开发者平台 创建内部集成或选择已有集成
2. 复制集成的 Secret Token（格式：ntn_****）
3. 访问目标页面，点击右上角「...」→「连接」→「连接到集成」

安装方式

NPM 安装（推荐）

NPM 安装是使用 Notion MCP Server 最便捷的方式，适用于 Cursor、Claude Desktop、Zed 等主流 AI 客户端。

# 使用 NOTION_TOKEN（推荐）
npx -y @notionhq/notion-mcp-server

# 或使用 OPENAPI_MCP_HEADERS（高级场景）
npx -y @notionhq/notion-mcp-server --transport http

资料来源：README.md:80-95

Docker 安装

#### 选项一：使用官方 Docker Hub 镜像

官方镜像 mcp/notion 托管在 Docker Hub，无需本地构建即可快速部署。

# 拉取官方镜像
docker pull mcp/notion

# 使用 NOTION_TOKEN 运行
docker run --rm -i -e NOTION_TOKEN="ntn_****" mcp/notion

资料来源：README.md:140-155

#### 选项二：本地构建 Docker 镜像

如果需要自定义配置或使用最新代码，可选择本地构建：

# 构建镜像
docker compose build

# 或使用 docker build
docker build -t notion-mcp-server .

构建配置如下：

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
CMD ["node", "bin/cli.mjs"]

资料来源：Dockerfile:1-10

services:
  notion-mcp-server:
    build: .
    container_name: notion-mcp-server
    environment:
      - NOTION_TOKEN=${NOTION_TOKEN}
    stdin_open: true
    tty: true

资料来源：docker-compose.yml:1-15

客户端配置

配置架构图

graph TD
    A[AI 客户端] --> B[MCP 配置文件]
    B --> C{传输模式}
    C -->|STDIO| D[notion-mcp-server 进程]
    C -->|HTTP| E[notion-mcp-server HTTP 服务]
    D --> F[Notion API]
    E --> F

Cursor / Claude Desktop

#### 配置路径

• Cursor: ~/.cursor/mcp.json
• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

#### 使用 NOTION_TOKEN（推荐）

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

#### 使用 OPENAPI_MCP_HEADERS（高级场景）

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
      }
    }
  }
}

资料来源：README.md:95-125

Zed 编辑器

Zed 通过 settings.json 的 context_servers 配置项支持 MCP 服务器。

{
  "context_servers": {
    "some-context-server": {
      "command": {
        "path": "npx",
        "args": ["-y", "@notionhq/notion-mcp-server"],
        "env": {
          "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
        }
      },
      "settings": {}
    }
  }
}

资料来源：README.md:75-88

GitHub Copilot CLI

#### 交互式配置

/mcp add

#### 手动配置

编辑 ~/.copilot/mcp-config.json：

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

资料来源：README.md:88-103

Docker 环境下的客户端配置

#### 使用 Docker Hub 镜像

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN",
        "mcp/notion"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

#### 本地构建镜像

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN=ntn_****",
        "notion-mcp-server"
      ]
    }
  }
}

资料来源：README.md:155-185

传输模式与认证

STDIO 传输模式（默认）

STDIO 是默认传输模式，通过标准输入输出与客户端通信：

npx -y @notionhq/notion-mcp-server

HTTP 传输模式

HTTP 传输模式启动一个 HTTP 服务器，适合远程部署和需要认证的场景：

npx @notionhq/notion-mcp-server --transport http --port 3000

服务器默认监听 http://0.0.0.0:3000/mcp。

资料来源：scripts/start-server.ts:20-35

认证机制

HTTP 传输模式支持 bearer token 认证：

#### 自动生成 token（仅开发环境）

npx @notionhq/notion-mcp-server --transport http

输出示例：

Generated auth token: a1b2c3d4e5f6789...
Use this token in the Authorization header: Bearer a1b2c3d4e5f6789...

#### 自定义 token（生产环境推荐）

# 通过命令行
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

# 或通过环境变量
AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http

#### 禁用认证（不推荐）

npx @notionhq/notion-mcp-server --transport http --disable-auth

#### HTTP 请求示例

curl -H "Authorization: Bearer your-token-here" \
     -H "Content-Type: application/json" \
     -H "mcp-session-id: your-session-id" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

资料来源：scripts/start-server.ts:1-50

命令行参数

notion-mcp-server [options]

Options:
  --transport <type>     传输类型: 'stdio' 或 'http'（默认: stdio）
  --port <number>         HTTP 服务器端口（默认: 3000）
  --auth-token <token>    Bearer token 认证
  --disable-auth          禁用认证
  --help, -h              显示帮助信息

Environment Variables:
  NOTION_TOKEN            Notion 集成 token（推荐）
  OPENAPI_MCP_HEADERS      JSON 格式的 Notion API 请求头
  AUTH_TOKEN              HTTP 传输认证 token

资料来源：scripts/start-server.ts:10-30

开发环境配置

本地开发设置

1. 链接本地包：

npm link

1. 配置 MCP 客户端：

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

1. 清理：

npm unlink

构建与测试

# 构建项目
npm run build

# 运行测试
npm test

# 监听模式开发
npm run dev

本地执行

npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server

资料来源：README.md:200-230

环境变量详解

注意：OPENAPI_MCP_HEADERS 中的 JSON 必须正确转义。在 shell 中使用时，建议使用单引号包裹整个 JSON 字符串。

资料来源：src/openapi-mcp-server/client/http-client.ts:1-30

参数反序列化

MCP 工具调用时，参数以字符串形式传递。服务器会自动反序列化 JSON 格式的参数字符串：

graph LR
    A[MCP 客户端<br/>参数值: '{"filter": {...}}'] --> B[字符串传递]
    B --> C[反序列化检查]
    C -->|JSON 对象/数组| D[解析为对象]
    C -->|其他| E[保持原值]

支持的类型：

• JSON 对象字符串：'{"key": "value"}'
• JSON 数组字符串：'["item1", "item2"]'
• 嵌套对象的递归反序列化

资料来源：src/openapi-mcp-server/mcp/proxy.ts:1-40

故障排除

常见问题

验证配置

1. 启动服务器并检查输出日志
2. 确认客户端成功连接（查看客户端日志）
3. 尝试执行简单命令如搜索页面

发布包

npm login
npm publish --access public

资料来源：README.md:230-235

相关文档

• 官方 README
• Notion API 文档
• MCP 协议规范

概述

Notion MCP Server 的 HTTP 客户端模块负责执行所有与 Notion API 的网络通信。该模块封装了底层的 HTTP 请求逻辑，将 OpenAPI 规范定义的 API 操作转换为可执行的 HTTP 调用。

核心职责包括：

• 构建符合 Notion API 规范的 HTTP 请求
• 处理请求参数（路径参数、查询参数、请求体）
• 管理请求头和认证信息
• 处理表单数据和二进制内容
• 转换响应格式

资料来源：src/openapi-mcp-server/client/http-client.ts:1-198

架构设计

模块结构

┌─────────────────────────────────────────────────────────────┐
│                    MCPProxy                                  │
│              (工具注册与请求路由)                             │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                   HttpClient                                 │
│              (HTTP 请求执行层)                                │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 参数处理    │ 请求构建   │ 响应转换   │ 错误处理     │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                   Notion API                                 │
│              (https://api.notion.com)                        │
└─────────────────────────────────────────────────────────────┘

HTTP 客户端类

HttpClient 类是网络请求的核心执行器，在初始化时接收基础配置：

资料来源：src/openapi-mcp-server/client/http-client.ts:18-23

HttpClient 实现详解

类初始化

export class HttpClient {
  constructor(
    private config: HttpClientConfig,
    private openApiSpec: OpenAPIV3.Document
  ) {
    this.api = this.createApiClient()
  }
}

构造函数完成以下初始化：

1. 存储配置参数
2. 创建 axios API 客户端实例
3. 准备处理 OpenAPI 规范中定义的请求

资料来源：src/openapi-mcp-server/client/http-client.ts:15-26

请求参数处理

HttpClient 根据 OpenAPI 规范中的参数定义，智能分配参数到不同的请求位置：

graph TD
    A[接收参数对象] --> B{存在 requestBody?}
    B -->|是| C{参数类型为 FormData?}
    B -->|否| D[将参数转为 URL 查询参数]
    C -->|是| E[设置 FormData Headers]
    C -->|否| F[设置 JSON Content-Type]
    D --> G[执行 HTTP 请求]
    E --> G
    F --> G

参数分配逻辑：

资料来源：src/openapi-mcp-server/client/http-client.ts:55-77

请求体处理

当没有定义 requestBody 且没有 FormData 时，所有剩余参数自动转为 URL 参数：

// Add all parameters as url parameters if there is no requestBody defined
if (!operation.requestBody && !formData) {
  for (const key in bodyParams) {
    if (bodyParams[key] !== undefined) {
      urlParameters[key] = bodyParams[key]
      delete bodyParams[key]
    }
  }
}

资料来源：src/openapi-mcp-server/client/http-client.ts:66-74

Content-Type 处理

HttpClient 根据请求内容类型动态设置请求头：

const hasBody = Object.keys(bodyParams).length > 0
const headers = formData
  ? formData.getHeaders()
  : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }

资料来源：src/openapi-mcp-server/client/http-client.ts:79-88

请求头管理

Headers Polyfill

由于 Node.js 18 之前版本不支持原生的 Headers 类，项目实现了兼容性 polyfill：

class PolyfillHeaders {
  private headers: Map<string, string[]> = new Map();

  public append(name: string, value: string): void {
    const key = name.toLowerCase();
    if (!this.headers.has(key)) {
      this.headers.set(key, []);
    }
    this.headers.get(key)!.push(value);
  }

  public get(name: string): string | null {
    const key = name.toLowerCase();
    if (!this.headers.has(key)) {
      return null;
    }
    return this.headers.get(key)!.join(', ');
  }
}

资料来源：src/openapi-mcp-server/client/polyfill-headers.ts:1-45

Polyfill 特性

响应头转换

axios 响应的 headers 对象会被转换为标准 Headers 实例：

const responseHeaders = new Headers()
Object.entries(response.headers).forEach(([key, value]) => {
  if (typeof value === 'string') {
    responseHeaders.append(key, value)
  }
})

资料来源：src/openapi-mcp-server/client/http-client.ts:103-108

请求执行流程

完整请求流程

sequenceDiagram
    participant 调用方
    participant MCPProxy
    participant HttpClient
    participant NotionAPI

    调用方->>MCPProxy: 调用工具
    MCPProxy->>HttpClient: executeOperation(operationId, params)
    HttpClient->>HttpClient: 解析 OpenAPI 操作定义
    HttpClient->>HttpClient: 分离 path/query/body 参数
    HttpClient->>HttpClient: 构建请求配置
    HttpClient->>NotionAPI: HTTP 请求
    NotionAPI-->>HttpClient: 响应数据
    HttpClient->>HttpClient: 转换响应头
    HttpClient-->>MCPProxy: 格式化响应
    MCPProxy-->>调用方: 返回结果

操作查找

每个 API 操作通过 operationId 查找对应的 HTTP 方法：

const operationFn = (api as any)[operationId]
if (!operationFn) {
  throw new Error(`Operation ${operationId} not found`)
}

资料来源：src/openapi-mcp-server/client/http-client.ts:75-78

配置与初始化

MCPProxy 中的 HTTP 客户端

MCPProxy 在初始化时创建 HttpClient 实例：

this.httpClient = new HttpClient(
  {
    baseUrl,
    headers: this.parseHeadersFromEnv(),
  },
  openApiSpec,
)

资料来源：src/openapi-mcp-server/mcp/proxy.ts:29-35

从环境变量解析请求头

项目支持通过 OPENAPI_MCP_HEADERS 环境变量配置请求头：

private parseHeadersFromEnv(): Record<string, string> {
  const headersEnv = process.env.OPENAPI_MCP_HEADERS
  if (headersEnv) {
    try {
      return JSON.parse(headersEnv)
    } catch {
      return {}
    }
  }
  return {}
}

常用配置示例：

{
  "Authorization": "Bearer ntn_xxxx",
  "Notion-Version": "2025-09-03"
}

资料来源：src/openapi-mcp-server/mcp/proxy.ts:15-26

服务端初始化

init-server.ts 负责加载 OpenAPI 规范并创建代理：

export async function initProxy(specPath: string, baseUrl: string | undefined) {
  const openApiSpec = await loadOpenApiSpec(specPath, baseUrl)
  const proxy = new MCPProxy('Notion API', openApiSpec)
  return proxy
}

资料来源：src/init-server.ts:44-50

错误处理

操作未找到

当 operationId 不存在于 API 客户端中时：

const operationFn = (api as any)[operationId]
if (!operationFn) {
  throw new Error(`Operation ${operationId} not found`)
}

文件读取错误

规范文件加载失败时的处理：

try {
  rawSpec = fs.readFileSync(path.resolve(process.cwd(), specPath), 'utf-8')
} catch (error) {
  console.error('Failed to read OpenAPI specification file:', (error as Error).message)
  process.exit(1)
}

资料来源：src/init-server.ts:22-27

传输层支持

STDIO 传输（默认）

默认情况下，MCP 服务器使用 STDIO 传输，适用于本地集成：

notion-mcp-server

HTTP 传输

支持 HTTP 传输模式，用于远程访问：

notion-mcp-server --transport http --port 3000

HTTP 传输需要认证令牌：

# 自动生成令牌
notion-mcp-server --transport http

# 自定义令牌
notion-mcp-server --transport http --auth-token "your-token"

资料来源：scripts/start-server.ts:1-40

最佳实践

请求头配置

推荐使用 NOTION_TOKEN 环境变量进行配置：

NOTION_TOKEN=ntn_xxxx notion-mcp-server

高级场景可使用 OPENAPI_MCP_HEADERS：

OPENAPI_MCP_HEADERS='{"Authorization": "Bearer ntn_xxxx", "Notion-Version": "2025-09-03"}' notion-mcp-server

本地开发测试

使用 npm link 创建全局符号链接进行本地测试：

npm link

配置客户端使用本地包：

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

总结

HTTP 客户端模块是 Notion MCP Server 与 Notion API 通信的桥梁。通过封装底层的 HTTP 请求逻辑，提供了：

• 参数自动路由：智能区分 path、query、body 参数
• 格式自动适配：根据内容类型设置正确的 Content-Type
• 跨版本兼容：Headers polyfill 确保 Node.js 18 以下版本兼容
• 配置灵活：支持环境变量和命令行参数配置

该设计遵循了单一职责原则，使网络请求处理与业务逻辑解耦，便于维护和测试。

认证体系概述

Notion MCP Server 采用双层认证架构：

资料来源：scripts/start-server.ts:1-100

graph TD
    A[客户端请求] --> B{传输类型}
    B -->|stdio| C[直接通信]
    B -->|http| D[传输层认证]
    
    D --> E{验证 Bearer Token}
    E -->|通过| F[解析请求]
    E -->|失败| G[401 未授权]
    
    F --> H{API 认证}
    H -->|NOTION_TOKEN| I[使用环境变量 Token]
    H -->|OPENAPI_MCP_HEADERS| J[使用自定义 Header]
    
    I --> K[调用 Notion API]
    J --> K

环境变量配置

NOTION_TOKEN（推荐方式）

Notion 集成令牌是访问 Notion API 的主要认证凭证。

NOTION_TOKEN=ntn_xxxxxxxxxxxxxxxxxxxx npx -y @notionhq/notion-mcp-server

配置位置：scripts/start-server.ts:26-27 在启动时读取环境变量

const notionToken = process.env.NOTION_TOKEN

注意：集成令牌需在 Notion 开发者门户中创建，并为目标页面授予访问权限。

OPENAPI_MCP_HEADERS（高级配置）

当需要自定义请求头时使用，如指定 Notion API 版本：

OPENAPI_MCP_HEADERS='{"Authorization": "Bearer ntn_xxxx", "Notion-Version": "2025-09-03"}' \
npx -y @notionhq/notion-mcp-server

Header 解析逻辑：src/init-server.ts:39-52 通过 parseHeadersFromEnv() 方法处理

private parseHeadersFromEnv(): Record<string, string> {
  const headersEnv = process.env.OPENAPI_MCP_HEADERS
  if (!headersEnv) return {}
  
  try {
    return JSON.parse(headersEnv)
  } catch {
    throw new Error('OPENAPI_MCP_HEADERS must be valid JSON')
  }
}

HTTP 传输层认证

当使用 --transport http 模式时，服务器启用额外的 Bearer Token 认证层。

命令行参数

资料来源：scripts/start-server.ts:1-35

认证模式

#### 自动生成令牌（仅限开发环境）

npx @notionhq/notion-mcp-server --transport http

服务器启动时会输出自动生成的令牌：

Generated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab
Use this token in the Authorization header: Bearer a1b2c3d4e5f6789...

#### 自定义令牌（推荐用于生产环境）

npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

#### 环境变量配置

AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http

优先级：--auth-token > AUTH_TOKEN 环境变量

资料来源：scripts/start-server.ts:17-24

令牌验证流程

sequenceDiagram
    participant C as 客户端
    participant S as MCP Server
    
    C->>S: HTTP POST /mcp (无 Authorization)
    S-->>C: 401 Unauthorized
    
    C->>S: HTTP POST /mcp (Bearer invalid-token)
    S-->>C: 401 Unauthorized
    
    C->>S: HTTP POST /mcp (Bearer valid-token)
    S->>S: 验证令牌
    S->>S: 解析 JSON-RPC 请求
    S->>C: JSON-RPC 响应

认证头传递机制

HTTP 客户端负责将认证信息传递给 Notion API：

graph LR
    A[环境变量] -->|OPENAPI_MCP_HEADERS| B[HttpClient]
    C[NOTION_TOKEN] -->|Bearer Token| B
    B --> D[Authorization: Bearer ntn_xxx]
    B --> E[Notion-Version: 2025-09-03]
    D --> F[Notion API]
    E --> F

资料来源：src/openapi-mcp-server/client/http-client.ts:1-50

客户端初始化

this.httpClient = new HttpClient(
  {
    baseUrl,
    headers: this.parseHeadersFromEnv(),
  },
  openApiSpec,
)

资料来源：src/openapi-mcp-server/mcp/proxy.ts:35-42

安全配置最佳实践

生产环境配置

Docker 环境配置

#### 方式一：使用 NOTION_TOKEN

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "NOTION_TOKEN", "mcp/notion"],
      "env": {
        "NOTION_TOKEN": "ntn_xxxx"
      }
    }
  }
}

#### 方式二：使用 OPENAPI_MCP_HEADERS

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "OPENAPI_MCP_HEADERS", "mcp/notion"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_xxxx\",\"Notion-Version\":\"2025-09-03\"}"
      }
    }
  }
}

Cursor/Claude Desktop 配置

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_xxxx"
      }
    }
  }
}

错误处理

// 错误处理示例
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid OpenAPI 3.1 specification:')
    error.errors.forEach(err => console.error(err))
  } else {
    console.error('Error:', error)
  }
  process.exit(1)
}

资料来源：scripts/start-server.ts:85-93

命令行帮助信息

Usage: notion-mcp-server [options]

Options:
  --transport <type>     Transport type: 'stdio' or 'http' (default: stdio)
  --port <number>        Port for HTTP server when using Streamable HTTP transport (default: 3000)
  --auth-token <token>   Bearer token for HTTP transport authentication (auto-generated if not provided)
  --disable-auth         Disable bearer token authentication for HTTP transport
  --help, -h             Show this help message

Environment Variables:
  NOTION_TOKEN           Notion integration token (recommended)
  OPENAPI_MCP_HEADERS    JSON string with Notion API headers (alternative)
  AUTH_TOKEN             Bearer token for HTTP transport authentication (alternative to --auth-token)

快速参考

概述

Notion MCP Server 支持两种传输层协议，用于与 MCP 客户端进行通信。传输层是 MCP 服务器与客户端之间数据传输的核心抽象，负责处理请求的序列化和反序列化、会话管理以及认证机制。资料来源：package.json

传输类型

资料来源：scripts/start-server.ts:1-50

stdio 传输模式

stdio（Standard Input/Output）是 MCP 协议的默认传输方式，适用于本地进程通信场景。在这种模式下，服务器通过标准输入读取来自客户端的 JSON-RPC 请求，并通过标准输出返回响应。

工作原理

graph LR
    A[MCP 客户端] -->|stdin| B[notion-mcp-server]
    B -->|stdout| A

stdio 传输模式的优势在于：

• 配置简单，无需额外的网络配置
• 适合自动化测试和本地开发
• 进程生命周期由客户端管理

使用方式

# 默认使用 stdio 传输
npx -y @notionhq/notion-mcp-server

# 显式指定 stdio 传输
npx @notionhq/notion-mcp-server --transport stdio

资料来源：scripts/start-server.ts:1-30

HTTP 传输模式

HTTP 传输模式基于 Model Context Protocol 的 Streamable HTTP 规范实现，提供了更灵活的远程访问能力。资料来源：scripts/start-server.ts:1-80

架构设计

graph TD
    A[MCP 客户端] -->|HTTP 请求| B[Express 服务器]
    B -->|路由| C[Streamable HTTP Handler]
    C -->|认证检查| D{认证状态}
    D -->|有效| E[MCP 代理]
    D -->|无效| F[401 Unauthorized]
    E -->|处理请求| G[Notion API]
    G -->|响应| E
    E -->|JSON-RPC 响应| B

启动参数

资料来源：scripts/start-server.ts:15-40

命令行示例

# 基础 HTTP 模式（自动生成认证令牌）
npx @notionhq/notion-mcp-server --transport http

# 指定端口
npx @notionhq/notion-mcp-server --transport http --port 8080

# 自定义认证令牌（推荐用于生产环境）
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

# 禁用认证（仅用于开发环境）
npx @notionhq/notion-mcp-server --transport http --disable-auth

资料来源：scripts/start-server.ts:10-45

认证机制

HTTP 传输模式强制使用 Bearer Token 认证，以防止未授权访问。

认证方式优先级

1. 命令行参数 --auth-token（最高优先级）
2. 环境变量 AUTH_TOKEN
3. 自动生成（仅开发模式）

认证流程

sequenceDiagram
    participant C as MCP 客户端
    participant S as MCP 服务器
    participant N as Notion API
    
    C->>S: HTTP 请求 + Authorization Header
    Note over S: 验证 Bearer Token
    alt 认证失败
        S-->>C: 401 Unauthorized
    else 认证成功
        S->>N: API 请求
        N-->>S: API 响应
        S-->>C: JSON-RPC 响应
    end

请求示例

curl -H "Authorization: Bearer your-token-here" \
     -H "Content-Type: application/json" \
     -H "mcp-session-id: your-session-id" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

环境变量配置

Notion MCP Server 支持多种环境变量配置方式，用于设置 API 凭证和自定义请求头。

配置参数

配置示例

# 方式一：使用 NOTION_TOKEN（推荐）
export NOTION_TOKEN="ntn_****"
npx @notionhq/notion-mcp-server --transport http

# 方式二：使用 OPENAPI_MCP_HEADERS
export OPENAPI_MCP_HEADERS='{"Authorization":"Bearer ntn_****","Notion-Version":"2025-09-03"}'
npx @notionhq/notion-mcp-server --transport http

# 方式三：使用 AUTH_TOKEN
export AUTH_TOKEN="secure-auth-token"
npx @notionhq/notion-mcp-server --transport http

客户端配置

Cursor / Claude Desktop

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Zed Editor

{
  "context_servers": {
    "some-context-server": {
      "command": {
        "path": "npx",
        "args": ["-y", "@notionhq/notion-mcp-server"],
        "env": {
          "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
        }
      },
      "settings": {}
    }
  }
}

GitHub Copilot CLI

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Docker 部署

方式一：使用官方镜像

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "NOTION_TOKEN", "mcp/notion"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

方式二：本地构建

docker compose build

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN=ntn_****",
        "notion-mcp-server"
      ]
    }
  }
}

核心组件架构

graph TD
    subgraph 传输层
        A[stdio 传输]
        B[HTTP 传输]
    end
    
    subgraph 核心服务
        C[MCPProxy]
        D[HttpClient]
        E[OpenAPIToMCPConverter]
    end
    
    subgraph 工具系统
        F[工具注册]
        G[参数反序列化]
        H[API 执行]
    end
    
    A --> C
    B --> C
    C --> D
    C --> E
    E --> F
    F --> G
    G --> H

MCPProxy 类

MCPProxy 是传输层与工具系统之间的桥梁，负责：

• 初始化 MCP 服务器实例
• 注册 OpenAPI 转换后的工具
• 处理请求参数的反序列化
• 执行 API 调用并返回响应

export class MCPProxy {
  private server: Server
  private httpClient: HttpClient
  private tools: Record<string, NewToolDefinition>
  private openApiLookup: Record<string, OpenAPIV3.OperationObject & { method: string; path: string }>
}

资料来源：src/openapi-mcp-server/mcp/proxy.ts:50-100

参数反序列化

MCP 协议在传输过程中会将嵌套对象序列化为字符串，服务器端需要反序列化这些参数：

function deserializeParams(params: Record<string, unknown>): Record<string, unknown> {
  // 处理 JSON 字符串形式的嵌套对象
  // 处理数组中的 JSON 字符串元素
  // 递归反序列化
}

资料来源：src/openapi-mcp-server/mcp/proxy.ts:10-50

配置决策矩阵

故障排除

常见问题

1. 连接被拒绝

• 检查端口是否被占用：lsof -i :3000
• 确认防火墙规则允许访问

1. 认证失败

• 验证 Bearer Token 与服务器配置一致
• 检查 Authorization 头部格式是否正确

1. 工具调用失败

• 确认 NOTION_TOKEN 有效且已配置到目标页面
• 检查 OpenAPI 请求头配置

调试模式

使用 tsx watch 启动开发服务器以获取详细日志：

npm run dev

资料来源：package.json:10-20

总结

Notion MCP Server 的传输层设计遵循 Model Context Protocol 规范，提供了 stdio 和 HTTP 两种传输模式以适应不同的部署场景。stdio 模式适合本地开发和测试，而 HTTP 模式则支持远程访问和微服务架构。通过命令行参数和环境变量的灵活组合，用户可以根据实际需求选择合适的认证和配置方案。

环境准备

系统要求

安装依赖

项目使用 ES Modules (ESM) 模块系统，TypeScript 版本为 5.8.2。安装依赖前请确保 Node.js 版本符合要求：

# 克隆仓库
git clone https://github.com/makenotion/notion-mcp-server.git
cd notion-mcp-server

# 安装依赖
npm install

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

环境变量配置

开发环境需要配置 Notion API 认证信息。可通过以下方式配置：

资料来源：README.md:100-120

项目架构

核心模块结构

notion-mcp-server/
├── scripts/
│   ├── notion-openapi.json    # OpenAPI 3.1.0 规范（所有工具的来源）
│   └── start-server.ts        # 服务器启动入口
├── src/
│   └── openapi-mcp-server/
│       ├── openapi/
│       │   └── parser.ts      # OpenAPI → MCP 工具转换
│       ├── mcp/
│       │   └── proxy.ts       # MCP 工具注册与执行
│       └── client/
│           └── http-client.ts # HTTP 请求执行
└── __tests__/                 # 测试文件目录

工具生成流程

MCP 工具通过 OpenAPI 规范自动生成，无需手动编写代码：

graph TD
    A[scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]
    B --> C[每个 operation 生成一个 MCP 工具]
    C --> D[参数 → inputSchema]
    C --> E[响应 → returnSchema]
    D --> F[MCPProxy.setupHandlers]
    E --> F
    F --> G[MCP SDK 注册工具]

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

开发命令

常用命令

资料来源：package.json:8-13

构建流程

npm run build 命令执行两个步骤：

1. TypeScript 编译：tsc -build 编译 TypeScript 源代码
2. CLI 打包：node scripts/build-cli.js 将代码打包为 CLI 可执行文件

构建产物：

• index.js：主入口
• bin/cli.mjs：CLI 可执行文件

# 完整构建
npm run build

# 仅编译 TypeScript（不打包 CLI）
tsc -build

# 热重载开发
npm run dev

资料来源：package.json:8

测试框架

Vitest 配置

项目使用 Vitest 4.0.18 作为测试框架，与 Vite 集成提供快速的单元测试能力。

测试文件位置遵循约定：与源文件同目录的 __tests__ 子目录：

src/openapi-mcp-server/openapi/
├── parser.ts
└── __tests__/
    └── parser.test.ts

运行测试时需要设置 NODE_ENV=test 环境变量：

# 运行所有测试
npm test

# 监听模式（文件变化时自动重新运行）
npm run test:watch

# 生成覆盖率报告
npm run test:coverage

资料来源：package.json:11-13

参数反序列化测试

proxy.ts 中的 deserializeParams 函数负责将 JSON 字符串参数反序列化为对象。测试覆盖以下场景：

• JSON 对象字符串 → 对象
• JSON 数组字符串 → 数组
• 嵌套对象的递归反序列化
• 无效 JSON 字符串保留原值

// 测试示例
const input = { filter: '[{"property":"Name","checkbox":{"equals":true}}]' }
const result = deserializeParams(input)
// result.filter 变为数组而非字符串

资料来源：src/openapi-mcp-server/mcp/proxy.ts:170-210

本地测试配置

Cursor 客户端测试

在 Cursor 中测试本地修改的步骤：

graph LR
    A[npm link] --> B[创建全局符号链接]
    B --> C[修改 mcp.json 配置]
    C --> D[Cursor 连接本地包]
    D --> E[测试 MCP 工具]
    E --> F{npm unlink 清理}

步骤 1：在仓库根目录创建符号链接

npm link

步骤 2：修改 Cursor 的 mcp.json 配置

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

步骤 3：测试完成后清理

npm unlink

资料来源：README.md:85-105

命令行直接执行

本地构建后可使用 npx 直接执行：

# 使用本地路径执行
npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server

HTTP 传输模式调试

启动带认证的 HTTP 服务器

# 自动生成认证令牌（仅用于开发）
npx @notionhq/notion-mcp-server --transport http

# 指定自定义令牌
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

# 使用环境变量指定令牌
AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http

启动参数说明

资料来源：scripts/start-server.ts:15-30

HTTP 请求示例

使用认证令牌发起请求：

curl -H "Authorization: Bearer your-token-here" \
     -H "Content-Type: application/json" \
     -H "mcp-session-id: your-session-id" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

Docker 开发

本地构建 Docker 镜像

# 构建镜像
docker compose build

# 运行容器
docker compose up

Docker 配置示例

使用环境变量传递 Notion 令牌（推荐）：

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN",
        "notion-mcp-server"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

使用 OPENAPI_MCP_HEADERS（高级场景）：

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENAPI_MCP_HEADERS",
        "notion-mcp-server"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2025-09-03\"}"
      }
    }
  }
}

资料来源：README.md:55-90

发布流程

npm 发布

# 登录 npm
npm login

# 发布包（需要 public 访问权限）
npm publish --access public

版本管理

当前版本：2.3.0

包名称：@notionhq/notion-mcp-server

发布前请确保：

1. 所有测试通过：npm test
2. 构建成功：npm run build
3. 更新版本号（在 package.json 中）

资料来源：package.json:4-7

OpenAPI 解析器开发

模式转换逻辑

parser.ts 实现了 OpenAPI Schema 到 JSON Schema 的转换：

graph TD
    A[OpenAPI Schema] --> B{类型判断}
    B -->|binary format| C[转换为 uri-reference]
    B -->|object| D[处理 properties]
    B -->|array| E[递归处理 items]
    B -->|enum| F[保留 enum 值]
    B -->|oneOf/anyOf| G[递归转换子模式]
    C --> H[JSON Schema]
    D --> H
    E --> H
    F --> H
    G --> H

关键转换规则

资料来源：src/openapi-mcp-server/openapi/parser.ts:1-80

常见问题排查

问题：模块导入错误

确保使用 ES Modules 运行，检查 package.json 中 "type": "module" 配置。

问题：测试找不到文件

检查测试文件是否位于源文件同级的 __tests__ 目录中，文件名应匹配 *.test.ts 模式。

问题：HTTP 认证失败

确认请求头中包含正确的 Authorization: Bearer <token>，且令牌与服务器配置一致。

问题：TypeScript 编译错误

运行 npm run build 前确保已安装所有依赖，必要时删除 node_modules 后重新安装。

概述

Notion MCP Server v2.0.0 是该项目的重大版本更新，主要迁移到 Notion API 2025-09-03 版本（即 Data Source Edition）。此次更新引入了 data sources（数据源） 作为数据库的主要抽象概念，取代了传统的 database 概念。

重要提示：v2.0.0 不需要代码更改。MCP 工具在服务器启动时自动被发现。当你升级到 v2.0.0 时，AI 客户端将自动看到新的工具名称和参数，旧版数据库工具将不再可用。

资料来源：README.md:100-105

版本变化总览

工具变化统计

资料来源：README.md:106-108

架构变化图示

graph TD
    subgraph v1.x 架构
        A1[数据库操作] -->|database_id| B1[post-database-query]
        A1 -->|database_id| B2[update-a-database]
        A1 -->|database_id| B3[create-a-database]
    end
    
    subgraph v2.0.0 架构
        A2[数据源操作] -->|data_source_id| C1[query-data-source]
        A2 -->|data_source_id| C2[update-a-data-source]
        A2 -->|data_source_id| C3[create-a-data-source]
        A2 -->|data_source_id| C4[retrieve-a-data-source]
        A2 -->|data_source_id| C5[list-data-source-templates]
    end
    
    A2 -.->|page_id / database_id| C6[move-page]
    A2 -.->|向后兼容| C7[retrieve-a-database]
    
    style A1 fill:#ffcccc
    style A2 fill:#ccffcc
    style B1 fill:#ffcccc
    style B2 fill:#ffcccc
    style B3 fill:#ffcccc
    style C1 fill:#ccffcc
    style C2 fill:#ccffcc
    style C3 fill:#ccffcc
    style C4 fill:#ccffcc
    style C5 fill:#ccffcc

移除的工具

以下三个工具已被新工具替代，不再可用：

资料来源：README.md:72-74

新增的工具

数据源操作工具

页面操作工具

资料来源：README.md:75-83

参数变更说明

核心参数变化

资料来源：README.md:84-87

参数转换示例

graph LR
    subgraph v1.x 参数传递
        A1["database_id: 'xxx'"] --> B1[数据库操作]
    end
    
    subgraph v2.0.0 参数传递
        A2["data_source_id: 'xxx'"] --> B2[数据源操作]
    end
    
    style A1 fill:#ffcccc
    style A2 fill:#ccffcc

API 版本与端点

使用的 API 版本

v2.0.0 使用 Notion API 版本 2025-09-03（Data Source Edition）。

此版本引入了数据源作为数据库的主要抽象，是 Notion API 的重大更新。

资料来源：CLAUDE.md:38

新增的 API 端点

资料来源：CLAUDE.md:39-40

迁移操作指南

步骤一：识别硬编码的工具引用

如果你的代码或提示词中硬编码了旧版工具名称，需要进行以下更新：

资料来源：README.md:117-121

步骤二：更新参数名称

# 数据库查询操作
- tool: "post-database-query"
- params: { "database_id": "xxx" }
+ tool: "query-data-source"
+ params: { "data_source_id": "xxx" }

# 数据库更新操作
- tool: "update-a-database"
- params: { "database_id": "xxx", ... }
+ tool: "update-a-data-source"
+ params: { "data_source_id": "xxx", ... }

步骤三：理解保留的工具

retrieve-a-database 工具仍然可用，用于获取数据库元数据。该工具现在会返回数据源 ID 列表。使用 retrieve-a-data-source 获取特定数据源的架构和属性。

graph TD
    A[retrieve-a-database] -->|获取数据库元数据| B[data_source_ids 列表]
    B --> C[retrieve-a-data-source]
    C -->|获取数据源架构| D[schema 和 properties]

资料来源：README.md:123-125

MCP 服务器工具自动发现机制

Notion MCP Server 的一个关键特性是工具自动生成机制。工具从 OpenAPI 规范自动派生，无需手动代码更改。

工具生成流程

graph TD
    A["scripts/notion-openapi.json<br/>OpenAPI 3.1.0 规范"] --> B["src/init-server.ts<br/>加载并验证规范"]
    B --> C["openapi/parser.ts<br/>OpenAPIToMCPConverter"]
    C --> D["convertToMCPTools() 方法"]
    D --> E["mcp/proxy.ts<br/>MCPProxy.setupHandlers()"]
    E --> F["MCP SDK 注册工具"]
    
    subgraph 关键转换逻辑
        C -.->|1. operationId → 工具名| G["retrieve-a-data-source"]
        C -.->|2. parameters + requestBody → inputSchema| H["输入参数模式"]
        C -.->|3. Response schema → returnSchema| I["返回模式"]
    end

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

文件结构说明

资料来源：CLAUDE.md:33-36

搜索功能变更

搜索过滤器值变化

v2.0.0 中，搜索 API 的过滤器值发生了以下变化：

graph LR
    A[搜索过滤器] -->|v1.x| B["value: 'database'"]
    A -->|v2.0.0| C["value: 'data_source'"]
    
    style B fill:#ffcccc
    style C fill:#ccffcc

资料来源：README.md:85-86

页面创建增强

新增的父级类型支持

v2.0.0 增强了页面创建功能，现在支持两种父级类型：

这使得在数据源中创建条目更加直接，无需先获取数据源对应的页面 ID。

资料来源：README.md:87-88

常见问题

Q1：是否需要修改代码？

否。MCP 工具在服务器启动时自动被发现。升级到 v2.0.0 后，AI 客户端会自动看到新的工具名称和参数。

唯一例外：如果你在代码或提示词中硬编码了旧版工具名称，则需要手动更新为新工具名称和参数。

资料来源：README.md:109-113

Q2：如何区分数据库和数据源？

• 数据库（Database）：传统概念，保留用于向后兼容
• 数据源（Data Source）：API 2025-09-03 引入的新概念，是当前的主要抽象

使用 retrieve-a-database 获取数据库元数据，其中包含关联的 data_source_ids 列表。

资料来源：README.md:123-125

Q3：如何获取数据源的详细信息？

使用 retrieve-a-data-source 工具获取特定数据源的架构和属性：

// 获取数据源详情
tool: "retrieve-a-data-source"
params: {
  "data_source_id": "<data_source_id>"
}

资料来源：README.md:77

环境变量配置

Notion 认证

HTTP 传输认证

资料来源：scripts/start-server.ts:1-30

构建和测试命令

常用命令

资料来源：CLAUDE.md:32

本地测试配置

1. 在仓库根目录运行 npm link 创建全局符号链接
2. 在 Cursor 的 mcp.json 中添加配置：

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

1. 测试完成后，运行 npm unlink 清理

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

总结

迁移检查清单

• [ ] 识别代码中硬编码的旧版工具名称
• [ ] 将 database_id 参数更新为 data_source_id
• [ ] 将搜索过滤器值从 "database" 更新为 "data_source"
• [ ] 验证 AI 客户端能自动发现新工具
• [ ] 测试数据源相关操作（查询、更新、创建）

关键变更一览

记住：最关键的迁移点是参数名称的变更（database_id → data_source_id）和搜索过滤器值的变化。只要更新这两处，你的应用就能平滑迁移到 v2.0.0。

概述

Notion MCP Server 的核心设计理念是通过 OpenAPI 3.1.0 规范文件自动生成 MCP 工具。文件上传功能是该架构中的重要组成部分，允许用户通过 MCP 协议上传本地文件到 Notion 服务端。

本文档详细说明 OpenAPI 规范解析机制与二进制文件上传处理的实现原理。

架构总览

scripts/notion-openapi.json
         ↓
   OpenAPI 3.1.0 规范
         ↓
src/openapi-mcp-server/openapi/parser.ts
         ↓
  OpenAPI → MCP 工具转换
         ↓
src/openapi-mcp-server/mcp/proxy.ts
         ↓
  MCP 工具注册与调用
         ↓
src/openapi-mcp-server/client/http-client.ts
         ↓
  Notion API HTTP 请求执行

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

OpenAPI 规范解析机制

规范文件结构

scripts/notion-openapi.json 是整个项目的核心数据源，采用 OpenAPI 3.1.0 标准定义所有 Notion API 端点：

资料来源：CLAUDE.md:21-22

Schema 转换流程

OpenAPIToMCPConverter 类负责将 OpenAPI Schema 转换为 MCP 可用的 JSON Schema：

convertOpenApiSchemaToJsonSchema(
  schema: OpenAPIV3.SchemaObject,
  resolvedRefs: Set<string>,
  resolveRefs: boolean
): IJsonSchema

转换过程中包含以下关键处理：

资料来源：src/openapi-mcp-server/openapi/parser.ts:1-100

二进制文件与上传处理

Binary 格式转换

当 OpenAPI Schema 中的 format 字段为 binary 时，解析器会自动进行以下转换：

if (schema.format === 'binary') {
  result.format = 'uri-reference'
  const binaryDesc = 'absolute paths to local files'
  result.description = schema.description 
    ? `${schema.description} (${binaryDesc})` 
    : binaryDesc
}

此转换使得 MCP 客户端可以传入本地文件的绝对路径，系统会自动处理文件上传逻辑。

资料来源：src/openapi-mcp-server/openapi/parser.ts:50-60

文件上传流程图

graph TD
    A[MCP 客户端调用工具] --> B[解析参数中的 binary 字段]
    B --> C{文件是否存在?}
    C -->|不存在| D[抛出参数错误]
    C -->|存在| E[读取本地文件内容]
    E --> F[构造 multipart/form-data 请求]
    F --> G[HTTP 客户端执行上传]
    G --> H{响应状态}
    H -->|2xx| I[返回成功结果]
    H -->|4xx/5xx| J[抛出 HttpClientError]

参数反序列化机制

参数处理策略

deserializeParams 函数解决了 MCP 协议传输过程中的双重序列化问题：

function deserializeParams(params: Record<string, unknown>): Record<string, unknown> {
  const result: Record<string, unknown> = {}
  
  for (const [key, value] of Object.entries(params)) {
    if (typeof value === 'string') {
      const trimmed = value.trim()
      if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
          (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
        // JSON.parse and validate...
      }
    }
    // ... more handling
  }
  return result
}

资料来源：src/openapi-mcp-server/mcp/proxy.ts:176-210

数组元素反序列化

数组内的 JSON 字符串元素也会被递归处理：

} else if (Array.isArray(value)) {
  result[key] = value.map((item) => {
    if (typeof item !== 'string') return item
    // ... check and parse JSON strings in array
  })
}

资料来源：src/openapi-mcp-server/mcp/proxy.ts:195-208

HTTP 客户端与请求执行

请求参数分类

HTTP 客户端将参数分为三类处理：

// 提取 path 和 query 参数
if (operation.parameters) {
  for (const param of operation.parameters) {
    if (param.in === 'path' || param.in === 'query') {
      if (params[param.name] !== undefined) {
        urlParameters[param.name] = params[param.name]
      }
    }
  }
}

// 无 requestBody 时，将 bodyParams 转为 URL 参数
if (!operation.requestBody && !formData) {
  for (const key in bodyParams) {
    if (bodyParams[key] !== undefined) {
      urlParameters[key] = bodyParams[key]
      delete bodyParams[key]
    }
  }
}

资料来源：src/openapi-mcp-server/client/http-client.ts:80-100

表单数据处理

当存在 formData 时，HTTP 客户端自动设置正确的 Content-Type 头：

const hasBody = Object.keys(bodyParams).length > 0
const headers = formData
  ? formData.getHeaders()
  : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }

资料来源：src/openapi-mcp-server/client/http-client.ts:110-115

工具注册与执行

MCP 工具生成

MCPProxy.setupHandlers() 方法负责将 OpenAPI 操作转换为 MCP 工具：

setupHandlers(tools: Record<string, { methods: NewToolMethod[] }>) {
  this.server.setRequestHandler(ListToolsRequestSchema, async () => {
    const toolDefs = []
    for (const method of methods) {
      toolDefs.push({
        name: method.name,
        description: method.description,
        inputSchema: method.inputSchema,
        annotations: {
          title: this.operationIdToTitle(method.name),
          ...(isReadOnly ? { readOnlyHint: true } : { destructiveHint: true }),
        },
      })
    }
    return { tools: toolDefs }
  })
}

资料来源：src/openapi-mcp-server/mcp/proxy.ts:150-170

工具调用处理

当 MCP 客户端调用工具时，系统执行以下步骤：

sequenceDiagram
    客户端->>MCP服务器: CallToolRequest(name, arguments)
    MCP服务器->>代理: findOperation(name)
    代理-->>MCP服务器: OperationObject
    MCP服务器->>参数反序列化: deserializeParams(arguments)
    参数反序列化-->>MCP服务器: deserializedParams
    MCP服务器->>HTTP客户端: executeOperation(operation, deserializedParams)
    HTTP客户端->>Notion API: HTTP Request
    Notion API-->>HTTP客户端: Response
    HTTP客户端-->>MCP服务器: response.data
    MCP服务器-->>客户端: { content: [{ type: 'text', text: JSON.stringify(data) }] }

错误处理

HTTP 客户端错误

HttpClientError 异常包含状态码和响应数据：

return {
  content: [
    {
      type: 'text',
      text: JSON.stringify(error.data?.response?.data ?? error.data ?? {}),
    },
  ],
  isError: true,
}

资料来源：src/openapi-mcp-server/mcp/proxy.ts:200-210

配置与运行环境

环境变量

命令行参数

notion-mcp-server [选项]

选项:
  --transport <type>  传输类型: 'stdio' 或 'http'
  --port <number>     HTTP 服务端口 (默认: 3000)
  --auth-token <token>  HTTP 传输认证令牌
  --disable-auth       禁用 HTTP 认证
  --help, -h          显示帮助信息

资料来源：scripts/start-server.ts:60-80

开发指南

本地测试文件上传

``bash npm run build ``

1. 构建项目：

``bash npm link ``

1. 链接本地包：

``json { "mcpServers": { "notion-local-package": { "command": "notion-mcp-server", "env": { "NOTION_TOKEN": "ntn_..." } } } } ``

1. 配置 MCP 客户端：

`` Upload file "/path/to/document.pdf" to page "My Page" ``

1. 测试文件上传：

``bash npm unlink ``

1. 清理：

资料来源：README.md:Development

相关资源

• OpenAPI 规范文件：scripts/notion-openapi.json
• Notion API 版本：2025-09-03 (Data Source Edition)
• API 端点类型：
• /v1/databases/{database_id} - 传统数据库端点
• /v1/data_sources/{data_source_id} - 新数据源端点

资料来源：CLAUDE.md:40-45

Pitfall Log / 踩坑日志

项目：makenotion/notion-mcp-server

摘要：发现 21 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：配置坑 - 来源证据：BUG: Tool query_data_sources not available。

1. 配置坑 · 来源证据：BUG: Tool `query_data_sources` not available

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool query_data_sources not available
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。

2. 配置坑 · 来源证据：Bug Report: Notion MCP — Status Property "in_progress" Group Options Not Recognized via API

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property "in_progress" Group Options Not Recognized via API
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安全/权限坑 · 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安全/权限坑 · 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

5. 安全/权限坑 · 来源证据：Notion MCP server does not work with Claude Code

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

6. 安全/权限坑 · 来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：Feature Request: Property-based filtering in notion-search for database queries

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。

8. 安装坑 · 来源证据：Ontheia listed as compatible client — works great with notion-mcp-server

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。

9. 配置坑 · 来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。

10. 配置坑 · 来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。

11. 配置坑 · 来源证据：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6ed1925ce08546dabe29e4f24e8a5967 | https://github.com/makenotion/notion-mcp-server/issues/281 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

13. 运行坑 · 来源证据：Schema quality: 8 required parameters missing descriptions

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Schema quality: 8 required parameters missing descriptions
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3874c96ff07545e58a89907777de0799 | https://github.com/makenotion/notion-mcp-server/issues/280 | 来源类型 github_issue 暴露的待验证使用条件。

14. 维护坑 · 来源证据：synced_block_reference: URL inside url= attribute gets auto-converted to <mention-page>, mangling the tag

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：synced_block_reference: URL inside url= attribute gets auto-converted to <mention-page>, mangling the tag
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_201ffa8849a546d7aa12e1ea13455afb | https://github.com/makenotion/notion-mcp-server/issues/286 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

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

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

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

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

18. 安全/权限坑 · 来源证据：v2.1.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6bd57dcedd924ba5a565340c6538b43c | https://github.com/makenotion/notion-mcp-server/releases/tag/v2.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

19. 安全/权限坑 · 来源证据：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR me…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR merge)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_805c993b34ef42b88c0832132f5794fc | https://github.com/makenotion/notion-mcp-server/issues/284 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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