AI导哈

Notion AI代理

一个基于Python的AI代理，通过官方模型上下文协议（MCP）连接到Notion工作区，利用Google的gemini-2.5-pro模型进行自然语言理解和任务执行。

  • by AmirUpSkill
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 amirupskill/notion-mcp

使用说明

MCP代理通知

一个强大的基于Python的AI代理，使用官方的模型上下文协议（MCP）连接到您的Notion工作区。它利用了谷歌最先进的技术 gemini-2.5-pro 通过LangChain进行建模，以理解自然语言命令，搜索您的Notion页面，并执行摘要等任务。

该项目是构建与Notion深度集成的更复杂的AI驱动应用程序的完美起点。

✨ 主要特点

  • 无缝概念集成：直接连接到Notion的官方托管MCP服务器。
  • 自然语言理解：用简单的英语提问（例如，“总结我的‘凤凰计划’PRD”）。
  • 由Gemini Pro提供技术支持：利用强大的LLM进行推理和任务执行。
  • 安全认证：使用以下方式安全地处理Notion OAuth mcp-remote 代理工具。
  • 可扩展：轻松添加更多工具和功能（例如，创建页面、更新数据库）。
  • 轻量级和现代堆栈：内置 mcp-useLangChain uv 获得快速、干净的开发体验。

⚙️ 技术栈

  • 语言：Python 3.11+
  • 人工智能框架：朗链， mcp-use
  • LLM：谷歌双子座2.5 Pro
  • 程序包管理器: uv
  • 核心协议：模型上下文协议（MCP）
  • 身份验证助手: mcp-remote （通过npm/npx）

🚀 入门指南

按照以下步骤在本地计算机上启动并运行Notion MCP代理。

先决条件

  • Python 3.11或更高版本
  • Node.js和npm（用于 mcp-remote 身份验证工具）
  • uv （一个快速的Python包安装程序）：
    pip install uv
  • Google Gemini API密钥：从 谷歌人工智能工作室.
  • 一个名义账户。

1.克隆存储库

git clone https://github.com/AmirUpSkill/Notion-MCP.git
cd Notion-MCP

2.设置环境

使用创建和激活虚拟环境 uv.

# Create the virtual environment
uv venv

# Activate it
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

3.安装依赖项

从以下位置安装所需的Python包 requirements.txt 文件。

uv pip install -r requirements.txt

4.配置您的API密钥

创建一个 .env 在项目根目录中的文件，以存储Gemini API密钥。

# Create the file (e.g., using 'touch' on macOS/Linux or 'echo.' on Windows)
touch .env

打开 .env 文件并添加密钥：

GEMINI_API="YOUR_GOOGLE_GEMINI_API_KEY_HERE"

这 config/mcp_config.json 文件已设置为使用 mcp-remote 用于Notion身份验证。那里不需要改变。

🏃‍♀️ 如何运行代理

首次运行：身份验证

第一次运行脚本时， mcp-remote 将自动打开您的web浏览器，进入Notion身份验证页面。

  1. 登录您的Notion帐户。
  2. 选择要授予代理访问权限的工作区和页面。
  3. 点击“允许访问".

成功授权后，您的凭据将在本地缓存（在 ~/.mcp-auth)，除非令牌过期或被撤销，否则您不需要再次执行此操作。

执行脚本

从终端运行主Python脚本：

python notion_mcp.py

代理将初始化、连接到Notion并执行脚本中的预定义任务。

自定义任务

要提出其他问题，只需编辑 notion_mcp.py 文件：

# in notion_mcp.py
...
# --- Example: Search Notion for a PRD ---
result = await agent.run(
    "Find the page titled 'Q3 Marketing Plan' and tell me the key objectives."
)
...

🔧 运作原理

代理人使用 mcp-use 库来管理与MCP服务器的连接。

  1. 客户端初始化：The MCPClient 读取 config/mcp_config.json.
  2. 本地代理：它找到了 notionMCP 服务器配置和运行 npx mcp-remote 作为本地子流程。
  3. 认证: mcp-remote 处理基于浏览器的OAuth2流，以从Notion获取安全访问令牌。
  4. 连接：当地 mcp-remote 该进程现在充当一个经过身份验证的代理，将请求从我们的Python脚本转发到Notion的托管MCP服务器(https://mcp.notion.com/mcp).
  5. 代理执行：The MCPAgent 将LLM的推理能力与Notion MCP服务器提供的工具（如 search 和 fetch)执行你的命令。

💡 故障排除

  • 401未经授权的错误：这通常意味着身份验证失败。
    • 确保你的浏览器没有屏蔽弹出窗口。
    • 清除身份验证缓存，然后重试：
      • 视窗: rmdir /s /q %USERPROFILE%\.mcp-auth
      • macOS/Linux: rm -rf ~/.mcp-auth
  • Google API配额错误：如果你看到 429 ResourceExhausted 错误，您已超过Gemini API的免费层限制。您可以等待配额重置，也可以在Google Cloud项目上设置更高限额的计费。

🗺️ 全面MVP路线图

该项目是基础客户。构建一个完整的“Notion AI Chat”应用程序的下一步将是：

  • 构建聊天界面：创建web UI（例如，使用Streamlit、Gradio或带有React前端的FastAPI）。
  • 实施更多工具：扩展代理以使用其他Notion工具，如 create-page, update-page，以及 create-comment.
  • 动态配置：添加UI元素以启用/禁用Notion连接。
  • 改进错误处理：为API错误或失败的工具调用提供用户友好的反馈。

📜 许可证

该项目根据MIT许可证获得许可。请参阅 LICENSE 文件以获取详细信息。

相关 MCP