Notion MCP Server 实操教程让 AI 用自然语言查询和写入 Notion 文档【免费下载链接】notion-mcp-serverOfficial Notion MCP Server项目地址: https://gitcode.com/gh_mirrors/noti/notion-mcp-server手动喂数据给 AI 的麻烦每周整理周报时你要从 Notion 的任务表里翻出本周完成的条目复制出来贴进 AI 工具再让它帮你写总结。想查一条记录就得在浏览器和聊天窗口之间来回切换想彻底自动化又得自己对着 Notion API 文档写请求代码。Notion MCP Server 解决的就是这类麻烦它把 Notion API 转换成 AI 可以直接调用的工具。接上之后你用一句自然语言说查本周完成的任务写进周报页面AI 自己完成查询和写入全程不用你碰 API。Notion MCP Server 是什么Notion 官方 MCP Server这个项目是 Notion API 的官方 MCPModel Context Protocol服务器。它在启动时读取 Notion 的 OpenAPI 规范把每个 API 端点自动转换成一个 MCP 工具AI 客户端可以发现并调用这些工具。它支持两种部署方式用 npx 直接运行或跑 Docker 镜像。客户端侧Cursor、Claude Desktop、Zed、GitHub Copilot CLI 都有对应的配置示例。Notion MCP Server 从 0 到跑通三步完成配置第 1 步创建内部集成登录 Notion在右上角头像菜单里进入My Integrations创建一个类型为Internal的新集成。创建后会得到一个以ntn_开头的 token这就是 AI 调用 Notion 时用的凭证。第 2 步把页面连接给集成集成只能看到你显式连接的页面。打开集成设置里的Access标签页点击 Edit勾选你想让 AI 操作的页面和数据库。也可以在具体页面里点右上角三个点选择Connect to integration逐个授权。第 3 步在客户端写入 MCP 配置以 Cursor 为例把下面这段加进.cursor/mcp.json。Claude Desktop 的结构相同只是配置文件位置不同{ mcpServers: { notionApi: { command: npx, args: [-y, notionhq/notion-mcp-server], env: { NOTION_TOKEN: ntn_**** } } } }把ntn_****换成第 1 步拿到的 token重启客户端。MCP 列表里出现notionApi并能列出一批 Notion 工具说明已连通。按任务分组看 Notion MCP Server 能力服务器一共提供 22 个工具。按你想干什么分其实是三类查数据search按关键词搜页面和数据源query-data-source带过滤条件和排序查询数据库记录retrieve-page-markdown把页面内容按 Markdown 读出来比逐块拉 JSON 省 tokenretrieve-a-page/retrieve-block-children获取页面和块内容的细节写内容create-a-page在指定父级下新建页面append-block-children向页面末尾追加块update-page-markdown用 Markdown 改页面支持整页替换和局部查找替换create-a-comment在页面上留评论管页面和数据库move-page移动页面到新位置update-a-page更新页面属性update-a-data-source调整数据库的属性配置这些名字不用背AI 会按你的指令自行挑选组合。一个完整任务演示从任务表生成周报在 Cursor 里输入这条指令查任务管理数据库里状态改为已完成且本周更新的任务按类别归纳写入项目周报页面。AI 的执行顺序大致是调search找到任务管理数据库的 ID用query-data-source按本周 已完成过滤查询把返回的记录按类别归纳调update-page-markdown把归纳结果写进项目周报页面全程不用开浏览器最后多出一个内容齐全的周报页面。如果第 1 步里你把集成配成了只读第 4 步会失败AI 会把归纳结果直接回复在聊天窗口里查询和整理部分不受影响。最小权限配置、密钥管理与性能调优先配最小权限。在集成设置的Capabilities标签页初始只勾Read contentAI 就只能查不能写。等确认输出符合预期再按需打开写权限。密钥管理。token 只应出现在本地配置文件中别把带 token 的配置文件提交进共享仓库。若用 HTTP transport 模式给网页端客户端用记得加--auth-token指定访问令牌服务器默认拒绝无令牌请求。调优建议查询一定带过滤条件限定范围裸查既慢又费 token读页面优先用retrieve-page-markdown别逐块拉取批量处理时让 AI 先用一次带排序的query-data-source取回全部结果再在结果上加工而不是逐个查询本地开发。想改服务器本身时克隆仓库并构建git clone https://gitcode.com/gh_mirrors/noti/notion-mcp-server cd notion-mcp-server npm install npm run build npm test工具由 scripts/notion-openapi.json 里的 OpenAPI 规范生成。新增一个 API 端点只需改这份规范src/openapi-mcp-server/openapi/parser.ts 的转换器会自动生成对应工具。常见报错排查连接失败、权限报错、响应慢客户端显示连接失败或看不到工具。原因通常是npx拉不到包或 token 还是占位符。先确认装好 Node手动跑一次npx -y notionhq/notion-mcp-server看有没有报错输出。搜索某个页面结果为空或报 404。该页面没连接给集成。去页面三个点菜单里选Connect to integration或在集成 Access 标签页补加。操作提示权限不足。token 的 Capabilities 配得太低去集成设置里核对是否勾选了对应读写权限。响应慢或 AI 提示内容过多。查询范围太大。加时间和状态过滤或改用按 Markdown 读页面。旧提示词报未知工具。2.0 版本删除了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。下一步先跑一个只读任务看 AI 如何调用工具、结果是否符合预期再按需打开写权限。熟悉之后可以从 scripts/ 的规范和 src/ 的源码开始做定制。【免费下载链接】notion-mcp-serverOfficial Notion MCP Server项目地址: https://gitcode.com/gh_mirrors/noti/notion-mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考