AI导哈

Notion自然语言查询服务器

一个提供对Notion工作区访问的模型上下文协议（MCP）服务器，允许用户通过自然语言查询搜索整个Notion工作区，使Notion数据可被MCP兼容应用访问。

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

使用说明

MCP服务器概念

提供对Notion工作区访问的模型上下文协议（MCP）服务器。此服务器允许您通过搜索整个Notion工作区来提出自然语言问题并获得全面的答案，使您的Notion数据可供MCP兼容的应用程序（如Roo Code和其他LLM客户端）访问。

特性

  • 自然语言查询：用简单的英语就Notion工作区中的任何内容提问
  • 综合搜索：搜索整个Notion工作区，而不仅仅是一个子集
  • 页面层次结构映射：自动发现并映射所有页面及其层次关系
  • 智能高速缓存：缓存页面映射以减少API调用并提高性能
  • 丰富的内容检索：以正确的格式从最相关的页面获取完整内容
  • 来源引用：始终包含返回原始Notion页面的链接
  • 富文本支持：处理各种Notion块类型，包括标题、列表、代码块等
  • 高级页面发现：按标题、路径或层次结构查找页面

运作原理

页面层次结构映射

服务器会自动构建整个Notion工作区的综合地图：

  1. 发现：从工作区获取所有页面和数据库
  2. 层次结构构建：在页面之间构造父子关系
  3. 路径映射：创建从根目录到每个页面的完整路径（例如，“项目>第四季度计划>会议笔记”）
  4. 智能高速缓存：将映射存储在 src/notion_mcp_server/resources/page_cache.json 具有可配置的过期时间
  5. 运行时更新：创建或更新页面时自动刷新缓存

查询处理

服务器提供多种工具用于与您的Notion内容交互：

问概念：自然语言查询

  1. 回答你的自然语言问题
  2. 在整个Notion工作区中搜索相关内容
  3. 从最相关的页面检索完整内容
  4. 将信息组合成一个全面的答案
  5. 提供指向响应中使用的所有页面的源链接

其他工具：页面管理和发现

  • list-notion-pages：浏览所有具有层次结构的页面
  • find-notion-page：按标题或路径查找特定页面
  • write-to-notion：创建或更新页面（具有自动缓存刷新功能）
  • refresh-notion-cache：手动刷新页面映射缓存

组件

资源

服务器将Notion页面作为自定义资源公开 notion:// URI方案：

  • 每个页面都可以通过以下方式访问 notion://page/{page_id}
  • 资源包括页面标题和描述
  • 内容以格式化的markdown文本形式返回

工具

服务器实现了几个用于全面的Notion交互的工具：

问概念：询问有关您的概念内容的任何问题

  • 将自然语言问题作为输入
  • 在整个Notion工作区中搜索相关信息
  • 返回包含源引用的综合答案
  • 可选择限制包含完整内容的页面数量（默认值：5个最相关）

写概念：创建或更新Notion页面

  • 在工作区级别或特定父页面下创建新页面
  • 按ID更新现有页面
  • 支持内容的markdown格式
  • 更改后自动刷新页面映射缓存

列出概念页面：浏览您的工作区结构

  • 列出所有具有层次缩进的页面
  • 按深度、存档状态和其他条件筛选
  • 显示页面ID、路径和URL以便于参考

查找概念页面：查找特定页面

  • 通过精确或模糊的标题匹配进行搜索
  • 按层次路径查找页面（例如，[“项目”、“Q4计划”]）
  • 返回详细的页面信息，包括完整路径和元数据

刷新概念缓存：更新页面映射

  • 强制刷新缓存的页面层次结构
  • 在服务器外部添加/修改页面时很有用
  • 提供有关工作区结构的摘要统计信息

设置

先决条件

  • Python 3.10或更高版本
  • 紫外线 包管理器
  • 包含您要访问的页面的Notion帐户
  • Notion集成令牌

安装

  1. 克隆此存储库：
git clone https://github.com/alecgrater/notion-mcp-server.git
cd notion-mcp-server
  1. 使用uv安装依赖项：
uv sync --dev --all-extras

  1. 创建Notion集成：

  2. 设置环境变量：

cp .env.example .env
# Edit .env and add your Notion token
  1. 与您的集成共享页面：
    • 在Notion中，转到您希望MCP服务器访问的页面
    • 点击右上角的“分享”
    • 点击“邀请”并选择您的集成
    • 授予适当的权限

配置

Roo代码

将服务器添加到Roo Code MCP配置中：

{
  "mcpServers": {
    "notion": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/notion-mcp-server",
        "run",
        "notion-mcp-server"
      ],
      "env": {
        "NOTION_TOKEN": "your_notion_integration_token_here"
      }
    }
  }
}

对于其他LLM客户

对于其他MCP兼容客户端，请使用以下配置服务器：

  • 命令: uv
  • 参数: ["--directory", "/path/to/notion-mcp-server", "run", "notion-mcp-server"]
  • 环境：设置 NOTION_TOKEN 到您的集成令牌

或者，如果你有 .env 在项目目录中的文件中，您可以省略环境配置：

{
  "mcpServers": {
    "notion": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/notion-mcp-server",
        "run",
        "notion-mcp-server"
      ]
    }
  }
}

用法

配置后，您可以通过询问有关Notion内容的问题，在首选LLM客户端中使用Notion MCP服务器：

  • “我目前的项目重点是什么？”
  • “查找有关第四季度规划会议的信息”
  • “我们从客户访谈中得到了什么反馈？”
  • “显示我关于新产品功能的笔记”
  • “上周会议的行动项目是什么？”

服务器将自动：

  1. 搜索您的整个Notion工作区
  2. 查找最相关的页面
  3. 提取并整合相关信息
  4. 提供一个全面的答案，并链接到源页面

发展

运行服务器

对于开发，您可以直接运行服务器：

uv run notion-mcp-server

测试

基本测试

运行基本功能测试以验证页面映射系统是否已正确设置：

uv run pytest tests/test_basic_pytest.py -v

这将测试：

  • 模块导入和依赖关系
  • 页面数据结构创建
  • 资源文件夹和缓存文件存在

集成测试

使用您的实际Notion工作空间进行测试（需要 NOTION_TOKEN 环境变量）：

uv run pytest tests/test_page_mapper_pytest.py -v

这将：

  • 连接到您的Notion工作区
  • 获取并映射所有具有层次结构的页面
  • 测试缓存功能
  • 验证搜索和发现功能

运行所有测试

要一次运行所有测试，请执行以下操作：

uv run pytest tests/ -v

VSCode集成

这些测试现在与pytest兼容，应该直接在VSCode的测试界面中工作。确保VSCode使用了正确的Python解释器(.venv/bin/python)对于该项目。

MCP检查员

您还可以使用MCP检查器测试服务器：

npx @modelcontextprotocol/inspector uv --directory . run notion-mcp-server

这将打开一个web界面，您可以在其中交互式地测试服务器的工具和资源。

建筑与出版

准备分发包裹：

  1. 同步依赖关系并更新锁文件：
uv sync
  1. 构建包分发：
uv build
  1. 发布到PyPI：
uv publish

故障排除

常见问题

  1. “NOTION_TOKEN环境变量是必需的”

    • 确保您已设置 NOTION_TOKEN 环境变量
    • 检查你的 .env 文件位于正确的位置
    • 验证令牌是否有效且未过期

  2. “未找到相关信息”

    • 确保您的集成已与要搜索的页面共享
    • 检查页面是否包含您要查找的内容
    • 试着重新表述你的问题或使用更广泛的术语

  3. “搜索Notion时出错”

    • 验证您的集成令牌是否正确且未过期
    • 检查您的集成是否具有必要的权限
    • 确保您有活动的互联网连接

调试

由于MCP服务器在stdio上运行，调试可能具有挑战性。为了获得最佳的调试体验，请使用 MCP检查员:

npx @modelcontextprotocol/inspector uv --directory . run notion-mcp-server

安全

  • 确保您的Notion集成令牌安全，永远不要将其提交给版本控制
  • 仅与您希望MCP服务器访问的页面共享您的集成
  • 定期审查和轮换您的集成令牌

相关 MCP