1. 为什么我要把 Notion 接进 agno 智能体Notion 用久了会有一个很具体的痛点页面越堆越多想批量改点东西、按条件找内容、给某段加评论全靠手点。Notion 官方虽然有 API但直接写 REST 调用要处理 block 嵌套、分页、rich_text 结构写两下就烦了。MCP模型上下文协议出现之后这件事变得顺手很多——它把 Notion 的能力包装成一组标准工具智能体可以像调函数一样去读写页面。这篇要讲的是把 Notion MCP 智能体跑在 agno 框架下用 OpenAI 模型驱动。agno 是一个偏轻量的智能体框架自带记忆、会话管理和 MCP 工具接入适合做这种「一个模型 一组工具 一个终端界面」的小案例。适合谁看已经会写点 Python、想用自然语言操作 Notion 的开发者或者你正在研究 MCP 怎么落地想找一个能完整跑通的例子。我会给出可复制的config.toml和settings.json骨架讲清楚怎么用 TaoToken 统一 Key 和 API 通道接入最后演示一次完整的智能体调用验证。整个过程不需要你改 Notion 的底层结构装完依赖配好 Key 就能对话。2. 前置准备TaoToken 统一 Key 与 API 通道在写代码之前先把模型通道这件事解决掉。agno 里调用 OpenAI 模型默认会走 OpenAI 官方地址但很多时候我们希望用一个统一的入口来管理 Key 和计费TaoToken 就是干这个的。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的接口格式所以 agno 的OpenAIChat只要改一下base_url就能接上。你需要先拿到一个 API Key。登录 TaoToken 控制台在 API Keys 页面创建一个新 Key复制出来。这个 Key 后面会写进.env文件作为OPENAI_API_KEY的值。注意别把它硬编码进代码里尤其是要提交到 Git 的时候。关于模型选择案例里用的是gpt-4o因为它在工具调用function calling上比较稳MCP 工具本质就是靠这个机制触发的。如果你换成别的模型要确认它支持 tool use否则智能体不会去调 Notion 的工具。这里有个容易踩的坑TaoToken 的 base_url 结尾不要多加/v1agno 内部会自己拼路径。我试过写成https://taotoken.net/api/v1结果请求 404排查了半天。正确写法就是https://taotoken.net/api。另外Notion 那边也需要一个集成令牌。去 Notion 的集成页面新建一个内部集成勾选读取和写入内容权限拿到ntn_开头的令牌。然后关键一步打开你要操作的 Notion 页面点右上角三个点选择「添加连接」把你刚建的集成加进去。不做这一步API 会返回 404因为集成没有权限访问这个页面。页面 ID 从 URL 里取。Notion 页面 URL 通常是https://www.notion.so/workspace/页面名-1f5b8a8bad058a7e39a6最后那串 32 位十六进制就是页面 ID。注意去掉中间的破折号或者保留都行Notion API 两种格式都认。3. 可复制配置config.toml 与 settings.json 骨架agno 本身不强制用配置文件但把参数抽出来会让代码干净很多。我习惯用一个config.toml存模型和智能体的设置再用settings.json存一些运行时开关。下面这两个骨架你可以直接复制。config.toml长这样[model] id gpt-4o base_url https://taotoken.net/api temperature 0.3 max_tokens 4096 [agent] name NotionDocsAgent markdown true retries 3 enable_user_memories true add_history_to_context true num_history_runs 5 [notion] api_version 2022-06-28 mcp_package notionhq/notion-mcp-server [storage] db_file agno.dbsettings.json用来控制一些行为开关比如是否流式输出、退出命令有哪些{ stream: true, markdown: true, exit_on: [exit, quit, bye, goodbye], user_label: You, emoji: }然后在 Python 里读这两个文件。读 toml 用标准库tomllibPython 3.11或者tomli读 json 用json。这样改参数不用动代码调试的时候很方便。.env文件放敏感信息NOTION_API_KEYntn_你的集成令牌 OPENAI_API_KEY你的TaoToken密钥 NOTION_PAGE_ID1f5b8a8bad058a7e39a6依赖装这几个pip install agno python-dotenv mcp openai sqlalchemy tomli如果你用的是 Python 3.10tomllib还没有装tomli就行导入时做个兼容判断。4. 核心代码把 Notion MCP 挂到 agno 智能体上代码结构分四层配置加载、MCP 连接、智能体创建、交互启动。我按顺序讲。先看导入和配置加载import asyncio import json import os import sys import uuid from textwrap import dedent import tomli from agno.agent import Agent from agno.models.openai import OpenAIChat from agno.tools.mcp import MCPTools from agno.db.sqlite import SqliteDb from mcp import StdioServerParameters from dotenv import load_dotenv load_dotenv() with open(config.toml, rb) as f: config tomli.load(f) with open(settings.json, r, encodingutf-8) as f: settings json.load(f) NOTION_TOKEN os.getenv(NOTION_API_KEY) TAOTOKEN_KEY os.getenv(OPENAI_API_KEY)MCP 服务器的连接参数是关键。Notion 官方提供了notionhq/notion-mcp-server这个 npm 包通过npx启动走 stdio 通信。认证信息放在环境变量OPENAPI_MCP_HEADERS里是一个 JSON 字符串server_params StdioServerParameters( commandnpx, args[-y, config[notion][mcp_package]], env{ OPENAPI_MCP_HEADERS: json.dumps({ Authorization: fBearer {NOTION_TOKEN}, Notion-Version: config[notion][api_version] }) } )注意Notion-Version这个头不传的话 Notion API 会用默认版本某些字段结构可能对不上。固定成2022-06-28比较稳。然后是智能体创建。agno 的Agent接收模型、工具、指令和存储async with MCPTools(server_paramsserver_params) as mcp_tools: db SqliteDb(db_fileconfig[storage][db_file]) agent Agent( nameconfig[agent][name], modelOpenAIChat( idconfig[model][id], api_keyTAOTOKEN_KEY, base_urlconfig[model][base_url] ), tools[mcp_tools], description通过 MCP 查询和修改 Notion 文档的智能体, instructionsdedent(f 你是一个专业的 Notion 助手帮助用户与他们的 Notion 页面进行交互。 重要指令 1. 你可以通过 MCP 工具直接访问 Notion 文档请充分利用它们。 2. 始终使用页面 ID: {page_id} 进行所有操作除非用户明确提供了另一个 ID。 3. 当被要求更新、读取或搜索页面时始终使用适当的 MCP 工具调用。 4. 进行更改时解释你做了什么并确认更改已完成。 5. 如果工具调用失败解释问题并建议替代方案。 ), markdownconfig[agent][markdown], retriesconfig[agent][retries], dbdb, enable_user_memoriesconfig[agent][enable_user_memories], add_history_to_contextconfig[agent][add_history_to_context], num_history_runsconfig[agent][num_history_runs] )base_url指向 TaoToken 的 API 地址这样模型请求就走统一通道了。enable_user_memories打开后agno 会把对话历史存进 SQLite下次同一用户 ID 进来还能记得之前聊过什么。最后启动交互式会话await agent.acli_app( user_iduser_id, session_idsession_id, usersettings[user_label], emojisettings[emoji], streamsettings[stream], markdownsettings[markdown], exit_onsettings[exit_on] )user_id和session_id用uuid生成每次运行都是新的。如果你想恢复上次会话把这两个值固定下来就行。5. 验证请求跑一次完整的智能体调用代码写完了跑起来看看。先确认npx能用Node.js 版本别太低建议 18 以上。然后python notion_mcp_agent.py 1f5b8a8bad058a7e39a6启动后会看到连接日志 Notion MCP 终端智能体 使用命令行提供的页面 ID: 1f5b8a8bad058a7e39a6 用户 ID: user_a1b2c3d4 会话 ID: session_e5f6g7h8 正在连接到 Notion MCP 服务器... 成功连接到 Notion MCP 服务器 Notion MCP 智能体已就绪开始与您的 Notion 页面对话。 输入 exit 或 quit 结束对话。然后输入第一句You: 我的 Notion 页面上有什么智能体会先调 MCP 工具去读页面内容再组织语言返回。你会看到它列出页面里的块结构比如标题、段落、列表。这一步验证的是「读」链路TaoToken 通道 → OpenAI 模型 → MCP 工具 → Notion API。接着试「写」You: 添加一个新段落内容是今天的会议记录智能体应该会调用创建块的工具返回类似「已在页面末尾添加段落」的确认。去 Notion 页面刷新一下能看到新段落。再试一个稍微复杂的You: 创建一个包含三个项目的无序列表苹果、香蕉、橙子这里要注意Notion 的列表块结构是嵌套的父块是bulleted_list_item子块才是文本。智能体如果处理得好会一次性创建三个列表项。如果它只创建了一个说明指令不够明确可以在 instructions 里补一句「创建列表时每个项目单独一个块」。验证成功的标志有三个终端里能看到工具调用日志、Notion 页面内容真的变了、智能体能记住上下文比如你接着问「刚才加了什么」它能答上来。6. 本篇常见错排查跑这个案例报错基本集中在几个地方。我按出现频率排一下。第一个npx找不到或超时。报错通常是FileNotFoundError: npx或者连接 MCP 服务器卡住。原因是 Node.js 没装或者不在 PATH 里。解决方法是装 Node.js 18然后npx -y notionhq/notion-mcp-server手动跑一次看能不能启动。如果卡在下载检查网络能不能访问 npm registry。第二个Notion API 返回 404。这个最常见八成是页面没共享给集成。去 Notion 页面右上角三个点 → 添加连接 → 选中你的集成。还有一种可能是页面 ID 取错了URL 里如果有查询参数要截掉?后面的部分。第三个模型不调工具。智能体回复「我无法访问 Notion」或者干脆不调 MCP。检查两点模型是不是支持 function callinggpt-4o支持一些老模型不支持base_url是不是写成了https://taotoken.net/api/v1多写/v1会导致请求路径错误工具调用直接失败。第四个OPENAPI_MCP_HEADERS格式错。这个环境变量必须是 JSON 字符串不是 Python dict。写成json.dumps({...})是对的直接传 dict 会报解析错误。另外Authorization的值是Bearer加令牌中间有空格别漏了。第五个记忆不生效。每次重启智能体都忘了之前聊的。检查user_id和session_id是不是每次随机生成。要持久化的话把这两个值写死或者存到文件里下次读出来复用。agno.db文件也要确认有写权限。第六个TaoToken 返回 401。Key 错了或者没传。确认.env里OPENAI_API_KEY是 TaoToken 控制台创建的 Key不是 Notion 的令牌。两个 Key 别搞混Notion 令牌是ntn_开头TaoToken 的 Key 格式不一样。7. 下一步把通道和工具用顺这个案例跑通之后你会发现 MCP 的价值在于「工具标准化」。Notion 只是其中一个 MCP 服务器同样的 agno 智能体结构换成别的 MCP 服务器就能操作别的服务代码几乎不用改。模型通道这边用 TaoToken 统一管理 Key 的好处是以后换模型或者加模型只改config.toml里的id和base_url不用动业务代码。如果你想把模型对话单独拿出来调试可以走模型对话入口直接测 prompt 和工具调用是否符合预期。长期做编码或者 Agent 开发的话Coding Plan 会更划算适合高频调用场景。接入过程中遇到 Key 或通道问题API Keys 页面能管理所有密钥接入文档里有各语言的示例。我自己的习惯是先把 MCP 服务器单独跑起来验证工具列表再挂到智能体上。这样出问题能快速定位是 MCP 层还是模型层。Notion 这个案例里npx -y notionhq/notion-mcp-server单独跑的时候会打印可用工具看到notion_read_page、notion_create_block这些名字心里就有底了。