使用说明

OneNote MCP服务器

OneNote MCP服务器是一个功能强大的模型上下文协议（MCP）服务器这使得像Claude这样的AI语言模型（LLM）和其他AI助手能够安全地与您的Microsoft OneNote数据交互。它允许阅读，编写、搜索和全面编辑OneNote笔记本，直接通过您的AI界面创建页面、部分和页面。

此服务器为高级OneNote管理提供了一套丰富的工具，包括健壮的文本提取、HTML内容处理和细粒度页面操作。

🆕 最新更新（2026年2月）

使用$orderby和$top进行查询优化，性能提高10-30倍！

✅ 服务器端排序 -Microsoft Graph做这项工作，而不是你的机器
✅ 智能限位 -仅获取最近的前N个页面（例如，7天内的70个页面）
✅ 单个API调用 -不再需要对数千页进行分页
✅ 响应时间 -典型值为60+秒至<5秒
✅ 利率限制友好 -API调用减少90%以上
✅ 动态优化 -根据时间窗口调整获取大小

查询优化详细信息→

团队笔记本支持渐进式加载！ 服务器现在可以正确支持具有即时性能的Microsoft Teams/SharePoint笔记本：

✅ 磁盘持久缓存 -服务器重启后，立即加载(.notebook-cache.json)
✅ 渐进式加载 -个人笔记本在2秒内完成，团队在后台加载
✅ 无超时 -与50多个团队完美合作
✅ 缓存实用程序 - refresh-cache.mjs 为其他应用程序预填充缓存
✅ 从SharePoint网站访问团队笔记本
✅ 列出团队笔记本中的分区（不再出现“资源ID不存在”错误）
✅ 搜索并获取团队笔记本中的最新更改
✅ 修复了显示名称问题(undefined → 专有名称）
✅ 基于全站点的端点路由 --所有工具（读取、搜索、创建、编辑）现在都可以路由 /sites/{siteId}/onenote 用于SharePoint笔记本，而不是通过失败 /me/onenote
✅ 编辑团队笔记本页面 --updatePageContent、appendToPage、replaceTextInPage、addNoteToPage、addTableToPage都适用于团队笔记本
✅ 在团队笔记本中创建页面 --createDailyNote和createPage现在支持团队笔记本
✅ getPageByTitle 当个人搜索未找到匹配项时搜索团队笔记本

团队笔记本文档→

特性

身份验证： 用于Microsoft Graph API访问的安全设备代码流。
读取操作：
- 列出支持完全分页的笔记本、分区和页面。
- 在所有笔记本中按标题搜索页面。
- 高级基于日期的搜索 在所有笔记本和分区中。
- 按创建或修改日期过滤页面（例如，查找今天的所有注释）。
- 内容搜索 -在页面内容中搜索，而不仅仅是标题。
- 按用户跟踪修改 -查看谁创建或最后修改了页面。
- 在特定笔记本电脑内进行范围搜索，以获得更好的性能。
- 获取各种格式的页面内容（完整HTML、可读文本、摘要）。
生产力工具：
- 站立准备助手 -快速查看自上次站立以来您修改了哪些页面。
- 快速创建每日笔记 -使用一个命令创建日期注释。
- 自动日期格式化（M/D/YY格式）。
- 智能重复检测（不会重新创建现有的每日笔记）。
分页和性能：
- 查询优化 -用途 $orderby 和 $top 查询速度提高10-30倍
- 使用67+台笔记本电脑和100+个分区高效处理帐户。
- 具有指数回退的自动重试逻辑，用于速率限制处理。
- 使用智能分页 @odata.nextLink 只有在需要的时候。
- 磁盘持久缓存 -笔记本列表已缓存到 .notebook-cache.json （5分钟TTL）
- 渐进式加载 -个人笔记本立即加载，团队在后台加载
- 缓存实用程序 - node refresh-cache.mjs 预填充缓存
- 在长时间运行的搜索过程中记录进度。
写入和编辑操作：
- 使用自定义HTML或markdown内容创建新的OneNote页面。
- 更新整个页面内容，保留或替换标题。
- 使用可选的时间戳和分隔符将内容附加到现有页面。
- 更新页面标题。
- 查找和替换页面中的文本（区分大小写或不区分大小写）。
- 在页面上添加格式化的笔记（如标注或待办事项）。
- 将结构化表格从CSV数据插入页面。
高级内容处理：
- 复杂的HTML到可读文本提取。
- 页面内容的Markdown到HTML转换。
稳健的输入验证： 使用Zod定义和验证工具输入模式。

先决条件

Node.js： 建议使用18.x或更高版本。（从安装 nodejs.org)
npm： 通常与Node.js捆绑在一起。
Git： 用于克隆存储库。（从安装 git-scm.com)
Microsoft帐户： 具有OneNote访问权限的活动Microsoft帐户。
Azure应用程序注册（建议用于生产/共享）：
- 而服务器默认使用Microsoft Graph Explorer的公共客户端ID便于测试，可供常规或共享使用，它是 强烈地推荐 创建自己的Azure应用程序注册。
- 确保您的应用程序注册具有以下委派的Microsoft Graph API权限： Notes.Read, Notes.ReadWrite, Notes.Create, User.Read.
- 用于访问共享笔记本和团队笔记本，还添加： Notes.Read.All, Notes.ReadWrite.All.
- 您需要从应用程序注册中获得“应用程序（客户端）ID”。

安装

克隆存储库：

git clone https://github.com/[your-github-username]/onenote-ultimate-mcp-server.git
cd onenote-ultimate-mcp-server

（替换 [your-github-username]/onenote-ultimate-mcp-server 使用您的实际存储库URL）

安装依赖关系：
```
npm install
```

配置

Azure客户端ID:

此服务器需要Azure应用程序客户端ID才能与Microsoft Graph进行身份验证。
- 建议用于生产/共享用途： 设置 AZURE_CLIENT_ID 将环境变量设置为您自己的Azure应用程序的“应用程序（客户端）ID”。
```
export AZURE_CLIENT_ID="your-actual-azure-app-client-id"
```
  （在Windows上，使用 set AZURE_CLIENT_ID=your-actual-azure-app-client-id)
- 快速测试： 如果 AZURE_CLIENT_ID 如果未设置环境变量，服务器将默认使用Microsoft Graph Explorer的公共客户端ID。这适用于初始测试，但不建议长期或共享使用。
- 或者，您可以修改 clientId 变量直接在 onenote-mcp.mjs，但优选使用环境变量。
.gitignore:

该项目包括 .gitignore 文件。确保它至少包含以下内容，以防止提交敏感文件：
```
node_modules/
.DS_Store
*.log
.access-token.txt
.notebook-cache.json
.env
```
这 .access-token.txt 服务器将创建一个文件来存储您的身份验证令牌。这 .notebook-cache.json 将创建文件来缓存您的笔记本列表，以获得更好的性能。

运行MCP服务器

配置后，从项目的根目录启动服务器：

node onenote-mcp.mjs

您应该看到控制台输出，指示服务器已启动并列出可用的工具类别。

连接到MCP客户端

您可以将此服务器连接到任何兼容MCP的客户端，如Claude Desktop或Cursor。

Claude桌面或光标示例：

打开MCP客户端的配置文件。
- 克劳德桌面（macOS）： ~/Library/Application Support/Claude/claude_desktop_config.json
- 克劳德桌面（Windows）： %APPDATA%\Claude\claude_desktop_config.json
- 光标： 首选项->MCP选项卡。

添加或更新 mcpServers 配置：

{
  "mcpServers": {
    "onenote": {
      "command": "node",
      "args": ["/full/path/to/your/onenote-ultimate-mcp-server/onenote-mcp.mjs"],
      "env": {
        // Recommended: Set AZURE_CLIENT_ID here if not set globally
        "AZURE_CLIENT_ID": "YOUR_AZURE_APP_CLIENT_ID_HERE"
      }
    }
  }
}

替换 /full/path/to/your/onenote-ultimate-mcp-server/ 随着 绝对路径 到您克隆存储库的位置。
替换 YOUR_AZURE_APP_CLIENT_ID_HERE 使用Azure应用程序的客户端ID，特别是如果您没有将其设置为系统范围的环境变量。

重新启动MCP客户端（克劳德桌面/光标）。

身份验证流程

第一次尝试通过AI助手或显式调用OneNote工具时 authenticate 工具：

调用 authenticate 工具： 您的AI助手将呼叫 authenticate 服务器上的工具。
设备代码提示： 服务器将输出一个URL（通常 https://microsoft.com/devicelogin)并为其添加用户代码 stderr。您的MCP客户端（例如Claude Desktop）应向您显示此信息。
浏览器身份验证： 在web浏览器中打开提供的URL并输入用户代码。
登录并授予权限： 使用具有OneNote访问权限的Microsoft帐户登录，并授予请求的权限。
已保存令牌： 浏览器身份验证成功后，服务器将自动接收访问令牌并将其保存到 .access-token.txt 文件在其目录中。
验证（可选但推荐）： 调用 saveAccessToken 通过您的AI助手使用该工具。此工具实际上不会保存（因为它已经被后台进程保存），而是加载和验证令牌，确认身份验证成功并显示您的帐户信息。

保存的令牌将用于后续会话，直到过期，此时您可能需要重新进行身份验证。

可用的MCP工具

此服务器向您的AI助手公开以下工具：

身份验证：

authenticate：使用Microsoft Graph启动设备代码身份验证流程。
saveAccessToken：加载并验证本地保存的访问令牌。
checkTokenScopes：解码JWT令牌以显示实际授予了哪些API权限（作用域）。使用此功能诊断笔记本可能未出现的原因。请参阅作者_博客制作.md 了解详情。

正在读取OneNote数据：

listNotebooks：列出所有OneNote笔记本。（Args： includeTeamNotebooks （布尔值，可选，默认值：false-为true时，包括您所属的Microsoft Teams中的笔记本。 需要注释。读。全部或注释。读写。所有权限。), refresh （布尔值，可选-强制缓存刷新）
- 注意：由于Microsoft API限制，不包括OneDrive中的个人共享笔记本。
- 新结果将缓存5分钟以获得更好的性能
- 新团队笔记本显示他们属于哪个团队
listSections：列出特定笔记本中的所有部分。（Args： notebookId （字符串）
- 固定的： 现在可以使用团队笔记本ID！
listPagesInSection：列出具有分页支持的特定部分中的页面。（Args： sectionId （字符串）， top （数量，可选，最多100个）， orderBy （枚举：“已创建”、“已修改”，可选）
searchPages: 优化！ 通过服务器端排序和分页，在所有笔记本中按标题搜索页面。（Args： query （可选字符串）， notebookId （可选字符串）， notebookName （可选字符串）， top （数字，默认100，最大100）， orderBy （枚举：“创建”、“修改”、“标题”，默认值：“修改”）， maxResults （数字，默认50，最大200）， includeTeamNotebooks （布尔值，默认值：false）
- 新用途 $orderby 和 $top 性能提高10-30倍
- 新可以按ID或名称搜索特定笔记本
- 新可配置的结果限制和排序顺序
- 新显示每个结果的笔记本名称
- 新 includeTeamNotebooks 通过基于站点的路由搜索SharePoint/Teams笔记本的选项
searchPagesByDate：在所有笔记本和分区中搜索在日期范围内创建或修改的页面。（Args： days （数字，默认值1）， query （可选关键字过滤器）， dateField （枚举：“创建”、“修改”、“两者都有”）， includeContent （布尔值，可选）， notebookName （可选字符串）， includeTeamNotebooks （布尔值，默认值：false）
- 优化： 用途 $orderby 和 $top API调用减少90%以上
- 新现在可以使用以下内容搜索团队笔记本 includeTeamNotebooks: true
- 新使用缓存的笔记本列表以获得更好的性能
- 智能取数限制：1天→ 20 页数，7天→ 70 页数，14+天→ 100 页数（最大）
searchPageContent: 新在页面内容中搜索文本（不仅仅是标题）。（Args： query （字符串）， days （可选编号）， notebookId （可选）， maxPages （默认值20））
searchInNotebook：在特定笔记本中使用可选日期和关键字过滤器进行范围搜索。（Args： notebookId （字符串）， query （可选字符串）， days （可选编号）， top （数量，最多100）
- 固定的： 现在可以使用团队笔记本ID！
getPageContent：检索特定OneNote页的内容。（Args： pageId （字符串）， format （枚举：“text”、“html”、“summary”，可选，默认值为“text”）
getPageByTitle：按页面标题查找页面并检索其内容。（Args： title （字符串）， format （枚举：“text”、“html”、“summary”，可选，默认值为“text”）

生产力工具：

getMyRecentChanges：显示您自某个日期以来修改的页面-非常适合站立准备！（Args： sinceDate （字符串或“星期一”）， days （可选编号）， notebookId （可选）， includeCreator （布尔值）
- 优化： 用途 $orderby 和 $top 查询速度提高了10-30倍（原来是60多秒，现在<5秒）
- 新通过要求防止超时 notebookId 当你有超过30个笔记本电脑时
- 固定的： 现在可以使用团队笔记本ID！
- 根据时间窗口（7天）动态调整页面获取限制→ 前70页）
createDailyNote：使用自动格式化的日期快速创建每日笔记。（Args： notebookName （字符串）， sectionName （字符串）， date （可选，默认为“今天”）， title （可选）， content （可选））

编辑和创建OneNote页面：

createPage：在第一个可用分区中创建新的OneNote页。（Args： title （字符串）， content （字符串-HTML或markdown）
updatePageContent：替换现有页面的全部内容。（Args： pageId （字符串）， content （字符串）， preserveTitle （布尔值，可选，默认值：true）
appendToPage：将新内容添加到现有页面的末尾。（Args： pageId （字符串）， content （字符串）， addTimestamp （布尔值，可选，默认值：true）， addSeparator （布尔值，可选，默认值：true）
updatePageTitle：更改现有页面的标题。（Args： pageId （字符串）， newTitle （字符串）
replaceTextInPage：查找并替换页面中的文本。（Args： pageId （字符串）， findText （字符串）， replaceText （字符串）， caseSensitive （布尔值，可选，默认值：false）
addNoteToPage：向页面添加格式化的带时间戳的注释/评论。（Args： pageId （字符串）， note （字符串）， noteType （枚举：“note”、“todo”、“important”、“question”、可选，默认值：“notes”）， position （枚举：“top”，“bottom”，可选，默认值：“bottle”）
addTableToPage：从CSV数据向页面添加格式化表。（Args： pageId （字符串）， tableData （字符串-CSV）， title （字符串，可选）， position （枚举：“top”，“bottom”，可选，默认值：“bottle”）

与AI交互示例

一旦连接并通过身份验证，您可以要求您的AI助手执行以下任务：

基本操作：

“列出我的OneNote笔记本。”
“显示我工作笔记本中的部分。”
“列出XYZ部分中的最新页面。”
“创建一个名为“会议创意”的新OneNote页面，内容为“头脑风暴新的营销策略”。”

高级搜索和发现：

“显示我今天创建或修改的所有笔记。”（使用 searchPagesByDate)
“查找过去7天内创建的所有提及“项目”的页面。”
“搜索过去3天标题中包含“会议”的页面。”
“在我的个人笔记本中，找到本周的所有页面。”
“在页面内容中搜索‘凤凰计划’”（搜索实际内容，而不仅仅是标题！）

生产力和站立准备：

“自周一以来，我修改了哪些页面？”（非常适合周四的脱口秀准备！）
“显示我最近3天的更改”
“在SQLNikon/Elon中创建今天的笔记”（自动格式化日期）
“在数据团队/单口相声中为2/20/26创建每日笔记”

内容操作：

“你能找到我关于‘凤凰计划’的OneNote页面并告诉我它的摘要吗？”
将“与John Doe跟进”添加到ID为“此处为您的页面ID”的OneNote页面
在我的OneNote页面“配方创意”中，将所有“糖”替换为“甜味剂”

故障排除

📋 常见问题及解决方案

🔐 未找到笔记本/结果为空？

如果您已通过身份验证，但 listNotebooks 不返回任何内容，这通常是 权限/范围问题.

→ 查看完整身份验证和权限故障排除指南

快速修复：

跑吧 checkTokenScopes 查看您拥有哪些权限的工具
如果丢失 Notes.Read.All 或 Notes.ReadWrite.All，您需要配置Azure AD应用程序注册
按照详细指南添加正确的API权限

身份验证问题：
- 确保您的 AZURE_CLIENT_ID （如果已设置）正确，并且具有所需的API权限。
- 如果设备代码流失败，请在其他浏览器或隐身/私人窗口中尝试。
- 令牌到期：如果工具停止工作，您可能需要重新运行 authenticate 工具。
- 空笔记本列表： 检查权限 checkTokenScopes -看作者_博客制作.md
服务器未启动：
- 检查Node.js版本(node -v).
- 确保安装了所有依赖项(npm install).
MCP客户端问题（例如，克劳德桌面、光标）：
- 验证 command 和 args （尤其是通往 onenote-mcp.mjs)客户端的MCP服务器配置是正确的。
- 更改配置后重新启动MCP客户端。
- 检查MCP客户端的日志和服务器的控制台输出是否有错误。

安全说明

访问令牌安全： 这 .access-token.txt 文件包含一个令牌，该令牌根据定义的范围授予对OneNote数据的访问权限。保护此文件，就像保护任何敏感凭据一样。确保它包含在您的 .gitignore 文件。
Azure客户端ID: 如果您创建了自己的Azure应用程序注册，请确保其客户端机密（如果为其他流生成）的安全。对于此设备代码流，此脚本不使用客户端机密。
权限： 此服务器请求 Notes.ReadWrite 和 Notes.Create 权限。请注意您授予的访问权限。

致谢

该项目是在灵感的启发下开发的，并采用了以下开源项目的模式：

onenote mcp 作者：danosb： 该项目为构建OneNote MCP服务器提供了早期灵感和参考，特别是关于身份验证和基本OneNote操作的初始概念。
azure onenote mcp服务器祖贝德·亨德里克斯著： 使用设备代码凭据、令牌存储/检索策略的核心身份验证流程，以及将Microsoft Graph API调用包装为OneNote（如列出实体和创建页面）作为MCP工具的基本模式，都是由该项目提供或改编的。该项目根据MIT许可证获得许可。

广泛的编辑工具集、高级文本提取和HTML处理实用程序、Zod模式集成以及该服务器的整体精细结构都是原创贡献。

该服务器的开发也得到了人工智能语言模型的协助，包括Anthropic的Claude和谷歌的Gemini，用于代码生成、重构、调试和文档编制等任务。

我们感谢参考项目的作者和人工智能工具的开发人员对开源和开发社区的贡献。

许可证

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

使用说明

OneNote MCP服务器

🆕 最新更新（2026年2月）

特性

先决条件

安装

配置

运行MCP服务器

连接到MCP客户端

身份验证流程

可用的MCP工具

与AI交互示例

故障排除

📋 常见问题及解决方案

安全说明

致谢

许可证

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

科学研究的开源MCP服务器