1. 项目概述与定位

@notionhq/notion-mcp-server 是 Notion 官方维护的本地 MCP（Model Context Protocol）服务器，它将 Notion API 暴露为一组可被 AI 客户端（Claude、Cursor、Zed、Gemini-CLI 等）直接调用的工具。当前 package 版本为 2.3.1，依赖 @modelcontextprotocol/sdk ^1.25.1，并通过 npm run build、npm test 等脚本完成构建与测试。资料来源：package.json:1-60

需要注意的是，README 顶部明确指出官方已推出远程 Notion MCP 服务（基于 OAuth），并计划在将来下线此本地仓库；该本地仓库目前不再主动监控 issue，远程服务的相关问题应提交至 Notion 官方支持渠道。资料来源：README.md:1-15

本地仓库内部使用 OpenAPI 规范作为"唯一事实来源"，所有 MCP 工具均由 scripts/notion-openapi.json 自动派生而来——因此新增接口通常无需修改 TypeScript 代码，只需更新 OpenAPI 规范即可。资料来源：CLAUDE.md:5-19

2. 核心架构与工具生成流程

服务器采用"OpenAPI → JSON Schema → MCP Tool"的三段式管线。OpenAPIToMCPConverter（位于 src/openapi-mcp-server/openapi/parser.ts）负责遍历 paths 中的所有 operation，把每个 operationId 转成工具名，把 parameters 与 requestBody 合并为 inputSchema，把响应模式转为 returnSchema。同时该转换器会递归展开 $ref，将 OpenAPI 的 format: binary 改写为 uri-reference（用于本地文件路径），并缓存已解析的 schema 以提升性能。资料来源：src/openapi-mcp-server/openapi/parser.ts:1-50 与 src/openapi-mcp-server/openapi/parser.ts:50-120

生成的工具随后在 MCPProxy.setupHandlers() 中注册到 MCP SDK 的 ListToolsRequestSchema 与 CallToolRequestSchema。当客户端发起调用时，proxy.ts 中的 deserializeParams() 会先将字符串化的嵌套对象还原为真正的 JSON，以规避部分客户端（如 Cursor、Claude Code）双重序列化的问题（参考 issue #176）。请求最终由 HttpClient.executeOperation() 发往 Notion API，响应以 JSON.stringify(response.data) 形式回传。资料来源：src/openapi-mcp-server/mcp/proxy.ts:1-50 与 src/openapi-mcp-server/mcp/proxy.ts:50-100

flowchart TD
    A[scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]
    B --> C[MCPProxy.setupHandlers]
    C --> D[注册到 MCP Server]
    E[MCP 客户端调用] --> F[deserializeParams]
    F --> G[HttpClient.executeOperation]
    G --> H[Notion API]
    H --> G --> E

认证模板则通过 Mustache 渲染，定义在 src/openapi-mcp-server/auth/template.ts 中，AuthTemplate 与 TemplateContext 类型由 src/openapi-mcp-server/auth/types.ts 提供。资料来源：src/openapi-mcp-server/auth/index.ts:1-2

3. 安装与客户端配置

3.1 在 Notion 侧创建集成

在 https://www.notion.so/profile/integrations 创建一个 internal 集成，并在「Configuration」中按需勾选能力，例如仅勾选 "Read content" 即可得到只读令牌，以降低 LLM 误操作风险。资料来源：README.md:35-55

随后在集成的「Access」标签页中选择目标页面，或在单个页面右上角的「··· → Connect to integration」中逐页授权。资料来源：README.md:57-75

3.2 在 MCP 客户端中注册服务器

推荐通过环境变量 NOTION_TOKEN 注入令牌；若需同时指定 API 版本，可使用 OPENAPI_MCP_HEADERS，例如 {"Authorization": "Bearer ntn_****", "Notion-Version": "2025-09-03"}。Cursor 与 Claude Desktop 的最小配置如下（写入 .cursor/mcp.json 或 ~/Library/Application Support/Claude/claude_desktop_config.json）：资料来源：README.md:80-110

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

服务器同时支持 SSE 与 HTTP 传输模式，可通过 port 参数开启本地 HTTP 端点（如 http://localhost:3000/mcp）。本地开发流程为：npm link → 修改 mcp.json 调用本地符号链接 → 测试完成 npm unlink 清理。资料来源：README.md:115-160

4. 重要版本变更与社区反馈

v2.0.0 已迁移至 Notion API 2025-09-03，引入 "data source" 作为数据库的主要抽象层。三个旧工具 post-database-query、update-a-database、create-a-database 分别被替换为 query-data-source、update-a-data-source、create-a-data-source，参数 database_id 也更名为 data_source_id；当前工具总数已扩展至 22 个。资料来源：README.md:17-35

社区中几个高互动问题与本页内容直接相关：

测试由 vitest 驱动，配置见 vitest.config.ts，npm run test:coverage 可生成覆盖率报告。资料来源：package.json:18-25 与 vitest.config.ts:1-7

See Also

• Tool Generation Pipeline（工具生成管线详解）
• Authentication Templates（认证模板与 Mustache 上下文）
• v2.0 Migration Guide（数据库 → 数据源迁移指南）

架构与 OpenAPI 到 MCP 工具生成

概述与设计目标

本仓库实现了一个 MCP (Model Context Protocol) 服务器，把 Notion REST API 包装为 AI 客户端可直接调用的工具。其核心设计理念是 "单一真相源"：所有工具均通过读取 scripts/notion-openapi.json 中的 OpenAPI 3.1 规范自动生成，开发者无需手动编写工具实现 资料来源：CLAUDE.md。

依据 README.md 中的说明，项目已迁移到 Notion API 2025-09-03 版本（Data Source Edition），将传统 database 概念升级为 data_source，工具总数由 19 个扩展为 22 个 资料来源：README.md。

整体架构管道

下面是规范到工具、再到 HTTP 调用的端到端数据流：

flowchart TD
    A[scripts/notion-openapi.json<br/>OpenAPI 3.1 规范] --> B[src/init-server.ts<br/>loadOpenApiSpec]
    B --> C[OpenAPIToMCPConverter<br/>parser.ts]
    C --> D[MCPProxy<br/>proxy.ts]
    D --> E[HttpClient<br/>http-client.ts]
    E --> F[Notion API v1<br/>api.notion.com]
    D --> G[MCP 客户端<br/>Claude / Cursor / Gemini-CLI]

入口脚本 scripts/start-server.ts 经由 src/init-server.ts:1-12 调用 initProxy()：先读取规范文件，再将可选 baseUrl 覆盖到 servers[0].url，最后构造 MCPProxy 实例 资料来源：src/init-server.ts:13-50。

OpenAPI 规范到工具的生成流程

解析阶段

OpenAPIToMCPConverter.convertToMCPTools() 遍历 paths 下每个 OperationObject，从中派生三类产物 资料来源：src/openapi-mcp-server/openapi/parser.ts:1-160：

工具名称随后在 MCPProxy 中被截断至 64 字符，并转换为人类可读标题（如 Create Database） 资料来源：src/openapi-mcp-server/mcp/proxy.ts:1-100。

注册阶段

MCPProxy 在构造时立即调用 setupHandlers()，向 MCP SDK 注册两类处理器：ListToolsRequestSchema 负责列出工具，CallToolRequestSchema 负责分发调用 资料来源：src/openapi-mcp-server/mcp/proxy.ts:1-100。在 ListTools 路径中，每个方法被包装为独立工具，并附带基于 HTTP 动词推导的 annotations：GET 操作得到 readOnlyHint: true，其它动词得到 destructiveHint: true，辅助大模型判断调用风险 资料来源：src/openapi-mcp-server/mcp/proxy.ts:1-100。

执行阶段

CallTool 处理器会先执行参数反序列化（用于修复某些 MCP 客户端对嵌套对象进行双重 JSON 序列化的问题，参见 PR #176），随后交由 HttpClient 实际发送请求 资料来源：src/openapi-mcp-server/mcp/proxy.ts:1-200。HttpClient 根据响应 Content-Type 在 text / image / binary 三种输出类型间切换，认证头优先采用 OPENAPI_MCP_HEADERS，缺省时回退到 NOTION_TOKEN 并自动附加 Notion-Version: 2025-09-03 资料来源：src/openapi-mcp-server/mcp/proxy.ts:1-200。

文件上传能力由独立的 src/openapi-mcp-server/openapi/file-upload.ts 模块提供：它扫描 requestBody.content['multipart/form-data'] 中 type: string, format: binary 的字段，将其识别为文件上传参数并通过 form-data 流式上传 资料来源：src/openapi-mcp-server/openapi/file-upload.ts:1-50。

已知局限与社区反馈

虽然工具由规范自动派生，但规范语义与实际使用之间仍存在差距，社区中已沉淀以下共识：

• 行内评论工具：notion-get-comments 当前以 page_id 作为入参，但 Notion 行内讨论按 block_id 索引；issue #175 建议将参数重命名为 block_id，需同步更新 OpenAPI 规范 资料来源：scripts/notion-openapi.json。
• Gemini-CLI 兼容性：issue #69 报告部分 MCP 客户端双重 JSON 序列化导致失败，目前通过 deserializeParams() 缓解但未根除 资料来源：src/openapi-mcp-server/mcp/proxy.ts:1-200。
• 访客用户访问：issue #227 反映 MCP 与 Notion API 一律拒绝 guest 用户，这是 Notion API 层面的限制，本仓库无法在工具层修复。
• 数据库查询能力：v2.0.0 已通过 query-data-source 替代 post-database-query，但复杂属性过滤仍受限于规范中的 filter 对象（issue #87）。

另请参阅

• README.md — 安装、配置与 v2.0.0 破坏性变更总览
• CLAUDE.md — 项目架构与常用命令
• package.json — 依赖与构建脚本

研究文档（引用来源参考）

(no reference document available)

传输模式、身份认证与部署

概述

Notion MCP Server 同时提供本地 stdio 与远程 Streamable HTTP 两种传输模式，并针对 Notion 调用与 HTTP 传输层分别提供独立的认证通道。当前发布版本 v2.3.1（见 package.json）已适配 Notion API 2025-09-03（Data Source Edition），工具总数为 22 个。本页围绕传输模式、身份认证与部署流程展开，帮助使用者快速完成本地集成与远程发布。

传输模式

服务器通过 CLI 参数 --transport 在两种模式之间切换，默认值为 stdio。

stdio 模式

stdio 是与 Claude Desktop、Cursor、Zed 等本地 MCP 客户端配合的默认模式。客户端以子进程方式启动 notion-mcp-server，通过标准输入输出收发 JSON-RPC 消息。README.md 中的 Cursor/Claude 示例即采用该方式：通过 npx -y @notionhq/notion-mcp-server 拉取并执行包入口 bin/cli.mjs。资料来源：README.md。

Streamable HTTP 模式

通过 --transport http 启用，可绑定到指定主机与端口。scripts/server-options.ts 将 HTTP 传输默认绑定到回环地址 127.0.0.1，端口默认为 3000，避免在未明确配置的情况下暴露到公网。资料来源：scripts/server-options.ts。可通过 --host 与 --port 显式覆盖，例如：

notion-mcp-server --transport http --host 0.0.0.0 --port 8080

scripts/server-options.test.ts 中的单元测试覆盖了上述默认值与覆盖逻辑。资料来源：scripts/server-options.test.ts:1-35。

flowchart LR
    A[MCP Client<br/>Claude/Cursor/Gemini] -->|stdio| B[notion-mcp-server<br/>子进程]
    A -->|HTTP + Bearer| C[Streamable HTTP<br/>127.0.0.1:3000]
    B --> D[Notion API v1/*]
    C --> D
    D --> E[Notion Workspace]

身份认证机制

认证分为两条独立链路：用于调用 Notion API 的应用层凭据，以及用于保护 HTTP 传输的 Bearer Token。

Notion API 凭据

• 推荐方式：设置环境变量 NOTION_TOKEN，值形如 ntn_****。资料来源：README.md。
• 高级方式：设置 OPENAPI_MCP_HEADERS，值为包含 Authorization 与 Notion-Version 的 JSON 字符串。src/openapi-mcp-server/mcp/proxy.ts 通过 parseHeadersFromEnv() 解析该变量，并将其注入到 HttpClient 头部。资料来源：src/openapi-mcp-server/mcp/proxy.ts:1-60。

集成 Token 需在 Notion Integrations 创建为 *internal* 类型，并通过「Access」选项卡授予具体页面/数据库访问权限。资料来源：README.md。

HTTP 传输层认证

启用 Streamable HTTP 后，服务器默认要求客户端在请求头中携带 Bearer Token。可通过以下方式注入：

• CLI 参数：notion-mcp-server --transport http --auth-token mytoken
• 环境变量：AUTH_TOKEN=mytoken notion-mcp-server --transport http
• 关闭认证：--unsafe-disable-auth（仅推荐隔离网络使用）
• 已弃用别名：--disable-auth 仍可识别但会触发告警

资料来源：scripts/server-options.ts:30-70。

为防止 DNS rebinding 攻击，scripts/server-options.ts 在关闭认证时自动启用 enableDnsRebindingProtection，并基于 host:port 计算 allowedHosts 与 allowedOrigins。资料来源：scripts/server-options.ts:50-90。

认证模板

src/openapi-mcp-server/auth/template.ts 使用 Mustache 渲染 OAuth 安全方案的 URL、Headers 与 Body，并将 Mustache.escape 重写为原样返回，避免 URL 中的 & 等字符被 HTML 转义。资料来源：src/openapi-mcp-server/auth/template.ts:1-15。模块由 src/openapi-mcp-server/auth/index.ts 统一导出，类型定义见 src/openapi-mcp-server/auth/types.ts。

部署与运行

安装与启动

最简方式是通过 npx 拉取并运行：

npx -y @notionhq/notion-mcp-server

package.json 在 bin 字段声明可执行入口 notion-mcp-server，对应产物为 bin/cli.mjs。资料来源：package.json:1-30。

构建与测试

• npm run build：执行 tsc -build 并调用 scripts/build-cli.js 打包 CLI 产物。资料来源：package.json:18-25。
• npm test：使用 vitest 运行 __tests__ 目录下的单元测试。资料来源：CLAUDE.md:30-45。
• npm run dev：通过 tsx watch 启动带热重载的开发服务器。资料来源：package.json:18-25。

本地联调

要在 Cursor 中验证本地修改：先在仓库根目录运行 npm link 建立全局符号链接，然后在 mcp.json 中将 command 配置为 notion-mcp-server。完成后可使用 npm unlink 清理。资料来源：README.md。

社区反馈与已知限制

• 访客用户访问受限：社区 Issue #227 报告 Notion MCP 完全拒绝工作区中的访客（guest）用户通过 OAuth 连接，提示需由 workspace owner 升级为 member。这是 Notion 官方 API 的限制，与本仓库的传输/认证实现无关。资料来源：community context #227。
• Gemini-CLI 兼容性：Issue #69 反馈 Gemini-CLI 在连接该服务器时报错，常见原因是 OPENAPI_MCP_HEADERS 不是合法 JSON，或 Notion-Version 与服务器声明的 2025-09-03 不一致。资料来源：community context #69。
• 双重 JSON 序列化修复：src/openapi-mcp-server/mcp/proxy.ts 在 CallToolRequestSchema 处理器中调用 deserializeParams，解决部分 MCP 客户端对工具参数进行了两次序列化的问题（PR #176）。资料来源：src/openapi-mcp-server/mcp/proxy.ts:30-60。
• 远程 MCP 优先级：README 顶部声明官方正在主推基于 OAuth 的远程 Notion MCP，未来可能停用本地服务器仓库，因此本仓库的 Issues 与 PR 不再被主动维护。资料来源：README.md。

See Also

• README.md
• CLAUDE.md
• scripts/server-options.ts
• 社区 Issue #227：访客用户连接限制
• 社区 Issue #69：Gemini-CLI 兼容性

1. v2.0.0 破坏性变更与迁移路径

Notion MCP Server 在 v2.0.0 切换到 Notion API 2025-09-03 版本，引入"data source"作为数据库的新抽象层。README 明确指出，部分 v1.x 工具被移除并被以 data source 命名的工具取代。资料来源：README.md。

1.1 工具与参数对照

下表整理了 v1.x → v2.0 工具的迁移关系。资料来源：README.md。

同时 retrieve-a-database 仍保留，用于返回包含 data source ID 列表的元数据；如需获取具体 schema 与属性，应改用 retrieve-a-data-source。另外，搜索工具的 filter.value 从 ["page", "database"] 改为 ["page", "data_source"]；创建页面时父级支持 page_id 和 database_id 两种形式。资料来源：README.md。

升级后工具总数从 19 增至 22，新增 list-data-source-templates、move-page 等 7 个工具，移除 3 个旧工具。资料来源：README.md。

1.2 迁移注意事项

MCP 客户端会在服务启动时自动发现工具，因此多数用户无需修改代码即可升级；但若业务提示词或脚本硬编码了旧工具名，需按上表手动调整。资料来源：README.md。

工具由 OpenAPI 规范自动生成：OpenAPIToMCPConverter.convertToMCPTools() 会遍历 scripts/notion-openapi.json 中的 paths 与 operation，并以 operationId 作为工具名。资料来源：src/openapi-mcp-server/openapi/parser.ts，同时 CLAUDE.md` 也确认了"工具由 OpenAPI 规范自动生成"的实现路径。资料来源：CLAUDE.md。

2. 已知功能限制

以下限制来自 Notion API 自身的策略与本地 MCP 服务的实现边界，不属于本地仓库可修复的缺陷。

2.1 访客（Guest）用户无法连接

社区反馈（#227）显示，使用访客账号进行 OAuth 连接时会收到："You are a guest, so you cannot connect to Notion MCP. Ask the workspace owner to upgrade you to a member, or switch workspaces." 该限制源自 Notion 官方 API 本身，并非本地 MCP 仓库可以绕过。资料来源：README.md（README 已说明本仓库可能将停止维护，建议迁移到远程 Notion MCP）。

2.2 缺少本地文件上传能力

社区（#191）多次请求支持本地文件/图片上传，但当前工具集对二进制上传的描述为"absolute paths to local files"，由 parser.ts 在 format === 'binary' 时自动将 format 改为 uri-reference。资料来源：src/openapi-mcp-server/openapi/parser.ts。但仓库并未提供完整的 multipart/form-data 透传链路与本地文件处理流程，因此 LLM 客户端上传任意本地文件仍不可用。

2.3 数据库查询能力依赖 data source 抽象

社区（#87）反馈希望直接对数据库进行复杂过滤/排序；v2.0 之前只能借助 search 工具实现近似查询。v2.0 后用户应改用 query-data-source，传入 data_source_id 与 filter / sorts 参数。资料来源：README.md。

3. 客户端兼容性与已修复问题

3.1 MCP 客户端双序列化 JSON 参数

v2.1.0 修复了 Cursor、Claude Code 等客户端对嵌套对象参数进行双重 JSON 序列化的问题。MCPProxy 的 CallToolRequestSchema 处理器会在执行前调用 deserializeParams()，递归检测字符串值并尝试 JSON.parse 以恢复正确结构。资料来源：src/openapi-mcp-server/mcp/proxy.ts。该机制同时记录了关联 issue 编号 (#176)，便于排查。

3.2 Gemini-CLI 等非主流客户端的兼容

社区（#69）报告 Gemini-CLI 在加载 Notion MCP 时报错。结合 mcp/proxy.ts 中的 setRequestHandler 注册模式：MCP SDK 通过 ListToolsRequestSchema 与 CallToolRequestSchema 两个标准通道提供服务能力。资料来源：src/openapi-mcp-server/mcp/proxy.ts。若客户端未正确实现 MCP 协议或协议版本不匹配，会出现工具发现失败。

3.3 `notion-get-comments` 参数语义

社区（#175）指出 get-comments 暴露的 page_id 无法获取块级行内评论。OpenAPI 规范声明 block_id 同时支持"block 或 page"，但 parser.ts 仅做透传不修改语义。资料来源：src/openapi-mcp-server/openapi/parser.ts，资料来源：README.md。建议在提示词中明确传入 block_id 以获取行内讨论。

4. 鉴权与运行模式注意事项

auth/template.ts 使用 Mustache 渲染鉴权 URL 与请求体，并禁用 HTML 转义以避免 URL 被破坏。资料来源：src/openapi-mcp-server/auth/template.ts。auth/types.ts 定义了 AuthTemplate / TemplateContext 等结构，包含 url、method、headers、body 字段。资料来源：src/openapi-mcp-server/auth/types.ts。

README 推荐使用 NOTION_TOKEN 环境变量；当使用 OPENAPI_MCP_HEADERS 高级模式时，需要手动序列化 JSON 字符串，并附加 Notion-Version: 2025-09-03。资料来源：README.md。当前版本号为 2.3.1（来自 package.json），启动脚本为 tsx watch scripts/start-server.ts，测试使用 vitest 并通过 vitest.config.ts 排除 node_modules 与 build 目录。资料来源：package.json，资料来源：vitest.config.ts。

See Also

• README.md — 安装、迁移表与运行模式说明
• CLAUDE.md — 仓库架构与生成工具流程
• Issue #191 — 本地文件上传能力请求
• Issue #227 — 访客用户访问限制
• Issue #69 — Gemini-CLI 兼容性
• Issue #175 — get-comments 行内评论
• Issue #87 — 数据库查询工具能力

Pitfall Log / 踩坑日志

项目：makenotion/notion-mcp-server

摘要：发现 14 个潜在踩坑项，其中 2 个为 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
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | 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
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：CLI version and unknown flags exit silently

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：CLI version and unknown flags exit silently
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/309 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：MCP serverInfo.version is hardcoded to 1.0.0 in package 2.2.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP serverInfo.version is hardcoded to 1.0.0 in package 2.2.1
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/310 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：Your project is now listed on CodeGuilds

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your project is now listed on CodeGuilds
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/306 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：package main points to missing index.js

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：package main points to missing index.js
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/307 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

7. 配置坑 · 来源证据：[Bug] Write operations fail on pages containing bookmark blocks

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] Write operations fail on pages containing bookmark blocks
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/298 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：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.

9. 运行坑 · 来源证据：Bug: `notion-update-page` / `insert_content` fails with "Invalid Notion page or block URL" on pages containing bookmark…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Bug: notion-update-page / insert_content fails with "Invalid Notion page or block URL" on pages containing bookmark blocks
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/296 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | release_recency=unknown