JinDaGe - mcp_onenote MCP Details

article

README

🚀 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。

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

步骤 3 — 添加 Microsoft Graph API 权限

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

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

| 权限 | 描述 | |-----------|-------------| | User.Read | 读取已登录用户的个人资料 | | Notes.Read | 读取 OneNote 笔记本 | | Notes.Create | 创建笔记本和页面 | | Notes.ReadWrite | 读取和修改 OneNote 笔记本 |

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

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

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

打开 https://microsoft.com/devicelogin
输入终端中显示的代码
使用你的 Microsoft 账户登录
将自动创建一个 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 服务器将可用。

💻 使用示例

可用工具

| 工具 | 描述 | 参数 | |-------|-------------|------------| | list_notebooks | 列出所有笔记本 | — | | list_sections | 列出笔记本的分区 | notebookId | | list_pages | 列出分区的页面 | sectionId | | read_content | 读取页面的内容（文本 + 图像） | pageId, extract_images（布尔值，默认值：true） | | create_notebook | 创建一个新的笔记本 | displayName | | create_section | 创建一个新的分区 | notebookId, displayName | | create_page | 创建一个新的页面 | sectionId, htmlContent |

图像提取（Claude Vision）

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

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

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

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 依赖项

主要依赖项

| 包 | 用途 | |---------|-------| | @modelcontextprotocol/sdk | MCP 服务器 | | @azure/msal-node | Microsoft 身份验证 | | @anthropic-ai/sdk | 用于图像的 Claude Vision | | node-fetch | HTTP 请求 | | dotenv | 环境变量 |

🔧 技术细节

安全性

包含密钥的 .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

mcp_onenote