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