MCP Onenote

🚀 MCP OneNote 服务器

这是一个适用于 Microsoft OneNote 的 模型上下文协议 (MCP) 服务器，它允许像 Claude Desktop 这样的人工智能代理读取、创建和分析 OneNote 的笔记本、分区和页面，还能通过 Claude Vision 自动提取图像内容。

🚀 快速开始

本项目需要一些前置条件并按照特定步骤进行安装和配置，才能正常使用 MCP OneNote 服务器。

✨ 主要特性

• 📒 列出 笔记本、分区和页面
• 📄 读取 页面的 HTML 内容
• 🖼️ 通过 Claude Vision 提取嵌入图像的文本（新增功能！）
• ✏️ 创建 笔记本、分区和页面
• 🔐 通过 Azure AD 设备代码流进行 身份验证

📦 安装指南

步骤 1 — 克隆项目

git clone https://github.com/FRESHSK/mcp_onenote.git
cd mcp_onenote_01
npm install

步骤 2 — 创建 Azure AD 应用（仅需执行一次）

此步骤用于获取访问 Microsoft Graph API 的 Client ID。

1. 访问 Azure 门户 - 应用注册
2. 点击 “新建注册”
3. 填写表单：
   • 名称：MCP OneNote
   • 支持的账户类型：选择第三个选项（多租户 + 个人 Microsoft 账户）
   • 重定向 URI：公共客户端/本机 → http://localhost
   • 点击 注册
4. 启用公共流：
   • 左侧菜单 → 身份验证
   • 向下滚动 → 高级设置
   • 允许公共客户端流 → 是
   • 点击 保存
5. 从 概述 中复制 应用程序（客户端）ID

步骤 3 — 添加 Microsoft Graph API 权限

创建 Azure AD 应用后，需要授予访问 OneNote 所需的权限。

1. 在 Azure 门户 中，访问你的应用注册
2. 左侧菜单 → API 权限
3. 点击 “添加权限”
4. 选择 Microsoft Graph
5. 选择 委托权限
6. 搜索并选中以下权限：

7. 点击 “添加权限”
8. 点击 “为 ... 授予管理员同意”（如果你是管理员），然后确认

ℹ️ 如果你不是管理员，权限将在首次通过设备代码流登录时授予。

Azure 门户中的预期结果：

✅ User.Read              (委托) - 已授予
✅ Notes.Read             (委托) - 已授予
✅ Notes.Create           (委托) - 已授予
✅ Notes.ReadWrite        (委托) - 已授予

步骤 4 — 配置环境变量

cp .env.example .env

编辑 .env 文件：

MICROSOFT_CLIENT_ID=你的 Azure 客户端 ID
MICROSOFT_TENANT_ID=common
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
TOKEN_CACHE_PATH=./token_cache.json

⚠️ 切勿将 .env 文件提交到版本库，它已包含在 .gitignore 中。

步骤 5 — 首次进行 Microsoft 身份验证

服务器需要一个 Microsoft 令牌来访问 OneNote。运行以下脚本一次：

node debug_auth.js

你将在终端中看到：

To sign in, use a web browser to open the page
https://microsoft.com/devicelogin and enter the code XXXXXXXX

1. 打开 https://microsoft.com/devicelogin
2. 输入终端中显示的代码
3. 使用你的 Microsoft 账户登录
4. 将自动创建一个 token_cache.json 文件

✅ 此步骤仅需执行一次。令牌将自动更新。

步骤 6 — 配置 Claude Desktop

编辑 Claude Desktop 的 claude_desktop_config.json 文件：

• Windows：C:\Users\<用户>\AppData\Roaming\Claude\claude_desktop_config.json
• Mac：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "onenote": {
      "command": "node",
      "args": [
        "C:\\绝对路径\\到\\mcp_onenote_01\\server.js"
      ],
      "env": {
        "TOKEN_CACHE_PATH": "C:\\绝对路径\\到\\mcp_onenote_01\\token_cache.json"
      }
    }
  }
}

⚠️ 绝对路径的 TOKEN_CACHE_PATH 对于 Claude Desktop 找到正确的令牌文件非常重要。

步骤 7 — 重启 Claude Desktop

关闭并重新启动 Claude Desktop。MCP OneNote 服务器将可用。

💻 使用示例

可用工具

图像提取（Claude Vision）

当 extract_images: true（默认值）时，read_content 工具将执行以下操作：

1. 解析页面的 HTML
2. 检测指向 Graph API 的 <img> 标签
3. 使用 Microsoft 令牌获取每个图像
4. 将图像发送到 Claude Vision 以提取文本内容
5. 返回文本 + 每个图像提取的内容

若要禁用此功能，请使用：

read_content(pageId: "...", extract_images: false)

📚 详细文档

项目结构

mcp_onenote_01/
├── server.js                   # 主 MCP 服务器
├── debug_auth.js               # 初始身份验证脚本
├── .env                        # 环境变量（不提交）
├── .env.example                # 环境变量模板
├── .gitignore                  # Git 忽略的文件
├── claude_desktop_config.json  # Claude Desktop 配置示例
├── token_cache.json            # MSAL 令牌缓存（不提交）
└── package.json                # Node.js 依赖项

主要依赖项

🔧 技术细节

安全性

• 包含密钥的 .env 文件已包含在 .gitignore 中
• 包含 Microsoft 令牌的 token_cache.json 文件已包含在 .gitignore 中
• 切勿将 API 密钥或令牌提交到 GitHub

故障排除

Claude Desktop 中 MCP 无响应？ → 检查日志：AppData\Roaming\Claude\logs\mcp-server-onenote.log

令牌过期并要求重新进行身份验证？ → 确保 claude_desktop_config.json 中的 TOKEN_CACHE_PATH 指向正确的绝对路径 → 重新运行 node debug_auth.js 以更新令牌

图像出现 media_type 错误？ → 如果 API Anthropic 不支持该类型，代码将自动将其规范化为 image/png

📄 许可证

MIT