Higress Notion MCP Server用一份 YAML 把 Notion REST API 变成 MCP 工具【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress在 AI Agent 应用中Notion 工作区是团队组织工作、管理项目和存储信息的核心协作环境而 Notion 的 REST API 为程序化读写工作区元素提供了入口。Higress 在plugins/wasm-go/mcp-servers/mcp-notion/下提供了一个Notion MCP Server把 Notion API 以声明式 YAML 的方式封装成标准 MCPModel Context Protocol工具让 AI 助手能够直接执行页面创建、数据库查询、用户管理、评论处理与内容搜索等操作。读完本文你将理解这个 MCP Server 暴露的全部工具、每个工具的参数与请求模板掌握从获取 Notion 集成 Key、生成 SSE URL 到配置 MCP Client 的完整接入流程并能看懂 Higress REST-to-MCP 引擎是如何把 YAML 模板渲染成真实 HTTP 请求的。功能概览根据 Notion MCP Server 文档该 Server 覆盖 Notion 工作区的五大类能力页面Pages创建、更新和检索页面内容数据库Databases管理数据库、属性、条目和模式用户Users访问用户配置文件和权限评论Comments处理页面和内联评论内容查询Content Queries搜索工作区内容。这些能力并非由 Go 代码逐行实现而是由一份声明式清单驱动。mcp-server.yaml 是这个 Server 的核心定义文件其中声明了一个名为notion-api-server的 Server配置项只有一个tokenNotion 集成 Token并注册了 15 个工具完整覆盖了上述五大能力域工具名功能HTTP 方法与路径Notion API关键参数getUser获取指定用户信息GET /v1/users/{user_id}user_id必填listUsers分页列出所有用户GET /v1/usersstart_cursor、page_size默认 100getCurrentUser获取当前认证用户信息GET /v1/users/me无queryDatabase查询数据库条目POST /v1/databases/{id}/querydatabase_id必填、filter_propertiessearch搜索页面和数据库POST /v1/searchquery、sortdirection/timestampgetBlock获取指定块信息GET /v1/blocks/{id}block_id必填updateBlock更新块内容PATCH /v1/blocks/{id}block_id必填、type、archiveddeleteBlock删除指定块DELETE /v1/blocks/{id}block_id必填getPage获取指定页面信息GET /v1/pages/{id}page_id必填、filter_propertiesupdatePage更新页面属性PATCH /v1/pages/{id}page_id必填、properties、in_trashcreateDatabase创建新数据库POST /v1/databasesparent必填、properties必填updateDatabase更新数据库PATCH /v1/databases/{id}database_id必填、titlegetDatabase获取数据库信息GET /v1/databases/{id}database_id必填getPageProperty获取页面属性项GET /v1/pages/{id}/properties/{pid}page_id、property_id均必填、分页参数createComment创建评论POST /v1/commentsparent必填、rich_text必填可以推断该清单的设计目标是“一个 Notion API 端点对应一个 MCP 工具”参数命名直接沿用 Notion API 的字段名如start_cursor、filter_properties、in_trash以便 LLM 能借助对 Notion API 的先验知识正确构造调用参数。配置结构详解mcp-server.yaml 的整体结构分为三层server: name: notion-api-server # Server 名称 config: token: # Notion 集成 TokenBearer Token tools: # 工具列表每个工具一个条目 - name: getCurrentUser description: 获取当前认证用户信息 requestTemplate: url: https://api.notion.com/v1/users/me method: GET headers: - key: Authorization value: Bearer {{.config.token}} - key: Notion-Version value: 2022-06-28 responseTemplate: body: | ## 当前用户 - **身份类型**: {{.type}} {{- if .bot}} - **所属者**: {{.bot.owner.user.name}} ({{.bot.owner.user.person.email}}) {{- end}}逐层说明如下1. server 层name指定 MCP Server 名称config.token是运行期注入的 Notion 集成 Token工具模板通过{{.config.token}}引用YAML 中不落盘真实凭据。2. 参数定义args每个参数的name、typestring/integer/boolean/array/object、required、default会被引擎转换为 MCP 工具的 JSON Schema 输入定义。例如listUsers的page_size声明了default: 100与描述“每页数量(默认100)”一致search的sort是 object 类型并声明了direction/timestamp两个子属性。3. requestTemplate定义如何把 MCP 调用渲染成对 Notion API 的 HTTP 请求常用字段包括url可内嵌 Go template 表达式如https://api.notion.com/v1/users/{{.args.user_id}}methodGET/POST/PATCH/DELETEheaders固定头 模板头。本清单中所有工具都强制带上Authorization: Bearer {{.config.token}}和Notion-Version: 2022-06-28即锁定了 Notion API 的 2022-06-28 版本契约bodyGo template 渲染的 JSON 请求体其中{{toJson .args.filter}}之类的写法用于把对象/数组参数整体序列化为 JSONargsToUrlParam: true把参数以 query 参数形式追加到 URLlistUsers、getPage、getPageProperty等 GET 工具均使用了该选项。4. responseTemplate.body把 Notion 的 JSON 响应渲染成对 LLM 更友好的 Markdown。例如listUsers会输出“用户列表(共N项)”并对每个用户生成名称、类型、最后编辑时间的小节getCurrentUser用条件模板{{- if .bot}}区分人person与机器人bot身份仅对 bot 额外展示所属者信息。这种“API 响应 → 结构化 Markdown”的转换是该 Server 的实用价值所在LLM 拿到的是紧凑、可读的文本而不是冗长的原始 JSON。REST-to-MCP 引擎的实现原理上述 YAML 之所以能直接运行是因为 Higress 内置了一个 REST-to-MCP 转换引擎其核心实现在 rest_server.go。从源码结构看RestTool结构体与 YAML 中的工具条目一一对应Args参数、RequestTemplateURL/Method/Headers/Body/ArgsToUrlParam等、ResponseTemplateBody/PrependBody/AppendBody另外还有Security、OutputSchema、ErrorResponseTemplate等可选字段RestToolArg支持Type、Required、Default、Enum、Items数组元素、Properties对象子属性以及Position参数在请求中的位置query/path/header/cookie/body——这解释了 mcp-notion 清单中type: objectproperties:的写法为何能生成合法的 JSON SchemaRestToolRequestTemplate.ArgsToJsonBody、ArgsToUrlParam、ArgsToFormBody三个开关互斥parseTemplates()会校验“三者最多只能设一个为 true”否则返回错误。mcp-notion 的 GET 类工具用ArgsToUrlParamPOST 类工具则显式写body模板正好符合这一约束模板解析阶段会把 URL、每个 header 的 value、body 分别编译为模板对象并注入getSocketIP、getRealIP等自定义函数可读取客户端真实 IP。因此{{.args.*}}、{{.config.*}}、{{toJson ...}}都是在这一层被求值的。配套的单测如 rest_server_test.go、config_validator_test.go覆盖了模板解析与配置校验路径说明这套 YAML 契约是引擎级保证的能力而不只是示例。如果想基于同样机制为自己开发新的 MCP Server可参考 MCP Server 实现指南其中给出了Description()/InputSchema()/Create()/Call()的 Go 代码式实现方式而 mcp-notion 展示的 YAML 声明式方式则是其中“纯 REST 映射”场景的最简形态。接入教程以下三步流程继承自 Notion MCP Server 文档适用于 Higress 托管的 MCP Server 平台。第一步获取 Notion 集成 Key在 Notion 中设置集成登录后进入个人资料页面下的 Integrations集成管理路径profile/integrations创建一个新的内部集成internal integration或选择一个已有的集成复制该集成对应的 Token。需要注意的适用前提Notion 集成对私有工作区的能力有限企业内部Enterprise工作区通常需要管理员授权集成默认只能访问你分享给它的页面与数据库。接入前请在 Notion 中打开目标页面/数据库通过“连接Connections”把该集成添加进去否则getPage、queryDatabase等工具会因无权限而失败该 Token 以 Bearer 方式随每个请求发送请妥善保管不要提交进代码仓库。第二步生成 SSE URL在 Higress MCP Server 平台界面登录后输入上一步获得的 Notion AccessToken平台会生成一个带{generate_key}的 SSE 端点 URL。从 mcp-server.yaml 的结构可以推断这个 key 就是用于把 Token 注入config.token配置并定位notion-api-server的凭据句柄从而为每次 SSE 会话建立带认证的 MCP 连接。第三步配置 MCP Client在用户的 MCP Client如各类 AI 助手/IDE 的 MCP 配置界面中将生成的 SSE URL 添加到 MCP Server 列表mcpServers: { notion: { url: https://mcp.higress.ai/mcp-notion/{generate_key}, } }其中{generate_key}替换为第二步实际生成的 key。配置完成后Client 通过 SSE 通道与网关中的notion-api-server通信随后即可调用上表 15 个工具。典型调用示例以“搜索工作区内容”为例Agent 调用search工具时的参数与网关发出的请求对应关系如下// MCP 工具调用参数 { query: Q3 项目计划, sort: { direction: descending, timestamp: last_edited_time } }网关按requestTemplate渲染后实际发出POST https://api.notion.com/v1/search Authorization: Bearer 你的集成Token Notion-Version: 2022-06-28 { query: Q3 项目计划, sort: {direction: descending, timestamp: last_edited_time} }响应再经responseTemplate.body渲染为“搜索结果”Markdown 列表标题、类型、最后编辑时间返回给 LLM。小结与注意事项Notion MCP Server 的全部行为由 mcp-server.yaml 一份清单定义15 个工具、1 个 Token 配置项覆盖页面、数据库、用户、评论、搜索五大能力域请求模板锁定Notion-Version: 2022-06-28如需升级 API 版本应在清单中同步调整请求头并核对参数兼容性写操作工具updateBlock、updatePage、createComment等会真实修改工作区内容建议在低敏感数据上先验证 Agent 的调用行为参数与模板的完整契约由 rest_server.go 中的 REST-to-MCP 引擎解析与校验扩展或排错时可对照该文件理解argsToUrlParam、toJson、条件模板等字段的语义。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Higress Notion MCP Server：用一份 YAML 把 Notion REST API 变成 MCP 工具
Higress Notion MCP Server用一份 YAML 把 Notion REST API 变成 MCP 工具【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress在 AI Agent 应用中Notion 工作区是团队组织工作、管理项目和存储信息的核心协作环境而 Notion 的 REST API 为程序化读写工作区元素提供了入口。Higress 在plugins/wasm-go/mcp-servers/mcp-notion/下提供了一个Notion MCP Server把 Notion API 以声明式 YAML 的方式封装成标准 MCPModel Context Protocol工具让 AI 助手能够直接执行页面创建、数据库查询、用户管理、评论处理与内容搜索等操作。读完本文你将理解这个 MCP Server 暴露的全部工具、每个工具的参数与请求模板掌握从获取 Notion 集成 Key、生成 SSE URL 到配置 MCP Client 的完整接入流程并能看懂 Higress REST-to-MCP 引擎是如何把 YAML 模板渲染成真实 HTTP 请求的。功能概览根据 Notion MCP Server 文档该 Server 覆盖 Notion 工作区的五大类能力页面Pages创建、更新和检索页面内容数据库Databases管理数据库、属性、条目和模式用户Users访问用户配置文件和权限评论Comments处理页面和内联评论内容查询Content Queries搜索工作区内容。这些能力并非由 Go 代码逐行实现而是由一份声明式清单驱动。mcp-server.yaml 是这个 Server 的核心定义文件其中声明了一个名为notion-api-server的 Server配置项只有一个tokenNotion 集成 Token并注册了 15 个工具完整覆盖了上述五大能力域工具名功能HTTP 方法与路径Notion API关键参数getUser获取指定用户信息GET /v1/users/{user_id}user_id必填listUsers分页列出所有用户GET /v1/usersstart_cursor、page_size默认 100getCurrentUser获取当前认证用户信息GET /v1/users/me无queryDatabase查询数据库条目POST /v1/databases/{id}/querydatabase_id必填、filter_propertiessearch搜索页面和数据库POST /v1/searchquery、sortdirection/timestampgetBlock获取指定块信息GET /v1/blocks/{id}block_id必填updateBlock更新块内容PATCH /v1/blocks/{id}block_id必填、type、archiveddeleteBlock删除指定块DELETE /v1/blocks/{id}block_id必填getPage获取指定页面信息GET /v1/pages/{id}page_id必填、filter_propertiesupdatePage更新页面属性PATCH /v1/pages/{id}page_id必填、properties、in_trashcreateDatabase创建新数据库POST /v1/databasesparent必填、properties必填updateDatabase更新数据库PATCH /v1/databases/{id}database_id必填、titlegetDatabase获取数据库信息GET /v1/databases/{id}database_id必填getPageProperty获取页面属性项GET /v1/pages/{id}/properties/{pid}page_id、property_id均必填、分页参数createComment创建评论POST /v1/commentsparent必填、rich_text必填可以推断该清单的设计目标是“一个 Notion API 端点对应一个 MCP 工具”参数命名直接沿用 Notion API 的字段名如start_cursor、filter_properties、in_trash以便 LLM 能借助对 Notion API 的先验知识正确构造调用参数。配置结构详解mcp-server.yaml 的整体结构分为三层server: name: notion-api-server # Server 名称 config: token: # Notion 集成 TokenBearer Token tools: # 工具列表每个工具一个条目 - name: getCurrentUser description: 获取当前认证用户信息 requestTemplate: url: https://api.notion.com/v1/users/me method: GET headers: - key: Authorization value: Bearer {{.config.token}} - key: Notion-Version value: 2022-06-28 responseTemplate: body: | ## 当前用户 - **身份类型**: {{.type}} {{- if .bot}} - **所属者**: {{.bot.owner.user.name}} ({{.bot.owner.user.person.email}}) {{- end}}逐层说明如下1. server 层name指定 MCP Server 名称config.token是运行期注入的 Notion 集成 Token工具模板通过{{.config.token}}引用YAML 中不落盘真实凭据。2. 参数定义args每个参数的name、typestring/integer/boolean/array/object、required、default会被引擎转换为 MCP 工具的 JSON Schema 输入定义。例如listUsers的page_size声明了default: 100与描述“每页数量(默认100)”一致search的sort是 object 类型并声明了direction/timestamp两个子属性。3. requestTemplate定义如何把 MCP 调用渲染成对 Notion API 的 HTTP 请求常用字段包括url可内嵌 Go template 表达式如https://api.notion.com/v1/users/{{.args.user_id}}methodGET/POST/PATCH/DELETEheaders固定头 模板头。本清单中所有工具都强制带上Authorization: Bearer {{.config.token}}和Notion-Version: 2022-06-28即锁定了 Notion API 的 2022-06-28 版本契约bodyGo template 渲染的 JSON 请求体其中{{toJson .args.filter}}之类的写法用于把对象/数组参数整体序列化为 JSONargsToUrlParam: true把参数以 query 参数形式追加到 URLlistUsers、getPage、getPageProperty等 GET 工具均使用了该选项。4. responseTemplate.body把 Notion 的 JSON 响应渲染成对 LLM 更友好的 Markdown。例如listUsers会输出“用户列表(共N项)”并对每个用户生成名称、类型、最后编辑时间的小节getCurrentUser用条件模板{{- if .bot}}区分人person与机器人bot身份仅对 bot 额外展示所属者信息。这种“API 响应 → 结构化 Markdown”的转换是该 Server 的实用价值所在LLM 拿到的是紧凑、可读的文本而不是冗长的原始 JSON。REST-to-MCP 引擎的实现原理上述 YAML 之所以能直接运行是因为 Higress 内置了一个 REST-to-MCP 转换引擎其核心实现在 rest_server.go。从源码结构看RestTool结构体与 YAML 中的工具条目一一对应Args参数、RequestTemplateURL/Method/Headers/Body/ArgsToUrlParam等、ResponseTemplateBody/PrependBody/AppendBody另外还有Security、OutputSchema、ErrorResponseTemplate等可选字段RestToolArg支持Type、Required、Default、Enum、Items数组元素、Properties对象子属性以及Position参数在请求中的位置query/path/header/cookie/body——这解释了 mcp-notion 清单中type: objectproperties:的写法为何能生成合法的 JSON SchemaRestToolRequestTemplate.ArgsToJsonBody、ArgsToUrlParam、ArgsToFormBody三个开关互斥parseTemplates()会校验“三者最多只能设一个为 true”否则返回错误。mcp-notion 的 GET 类工具用ArgsToUrlParamPOST 类工具则显式写body模板正好符合这一约束模板解析阶段会把 URL、每个 header 的 value、body 分别编译为模板对象并注入getSocketIP、getRealIP等自定义函数可读取客户端真实 IP。因此{{.args.*}}、{{.config.*}}、{{toJson ...}}都是在这一层被求值的。配套的单测如 rest_server_test.go、config_validator_test.go覆盖了模板解析与配置校验路径说明这套 YAML 契约是引擎级保证的能力而不只是示例。如果想基于同样机制为自己开发新的 MCP Server可参考 MCP Server 实现指南其中给出了Description()/InputSchema()/Create()/Call()的 Go 代码式实现方式而 mcp-notion 展示的 YAML 声明式方式则是其中“纯 REST 映射”场景的最简形态。接入教程以下三步流程继承自 Notion MCP Server 文档适用于 Higress 托管的 MCP Server 平台。第一步获取 Notion 集成 Key在 Notion 中设置集成登录后进入个人资料页面下的 Integrations集成管理路径profile/integrations创建一个新的内部集成internal integration或选择一个已有的集成复制该集成对应的 Token。需要注意的适用前提Notion 集成对私有工作区的能力有限企业内部Enterprise工作区通常需要管理员授权集成默认只能访问你分享给它的页面与数据库。接入前请在 Notion 中打开目标页面/数据库通过“连接Connections”把该集成添加进去否则getPage、queryDatabase等工具会因无权限而失败该 Token 以 Bearer 方式随每个请求发送请妥善保管不要提交进代码仓库。第二步生成 SSE URL在 Higress MCP Server 平台界面登录后输入上一步获得的 Notion AccessToken平台会生成一个带{generate_key}的 SSE 端点 URL。从 mcp-server.yaml 的结构可以推断这个 key 就是用于把 Token 注入config.token配置并定位notion-api-server的凭据句柄从而为每次 SSE 会话建立带认证的 MCP 连接。第三步配置 MCP Client在用户的 MCP Client如各类 AI 助手/IDE 的 MCP 配置界面中将生成的 SSE URL 添加到 MCP Server 列表mcpServers: { notion: { url: https://mcp.higress.ai/mcp-notion/{generate_key}, } }其中{generate_key}替换为第二步实际生成的 key。配置完成后Client 通过 SSE 通道与网关中的notion-api-server通信随后即可调用上表 15 个工具。典型调用示例以“搜索工作区内容”为例Agent 调用search工具时的参数与网关发出的请求对应关系如下// MCP 工具调用参数 { query: Q3 项目计划, sort: { direction: descending, timestamp: last_edited_time } }网关按requestTemplate渲染后实际发出POST https://api.notion.com/v1/search Authorization: Bearer 你的集成Token Notion-Version: 2022-06-28 { query: Q3 项目计划, sort: {direction: descending, timestamp: last_edited_time} }响应再经responseTemplate.body渲染为“搜索结果”Markdown 列表标题、类型、最后编辑时间返回给 LLM。小结与注意事项Notion MCP Server 的全部行为由 mcp-server.yaml 一份清单定义15 个工具、1 个 Token 配置项覆盖页面、数据库、用户、评论、搜索五大能力域请求模板锁定Notion-Version: 2022-06-28如需升级 API 版本应在清单中同步调整请求头并核对参数兼容性写操作工具updateBlock、updatePage、createComment等会真实修改工作区内容建议在低敏感数据上先验证 Agent 的调用行为参数与模板的完整契约由 rest_server.go 中的 REST-to-MCP 引擎解析与校验扩展或排错时可对照该文件理解argsToUrlParam、toJson、条件模板等字段的语义。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考