OneNote-MCP-For-GeminiSpark

一个用于 Microsoft OneNote 与 Gemini Spark 集成的稳健 Model Context Protocol (MCP) 服务器。本仓库包含代码、配置和示例，用于将 OneNote 内容与 GeminiSpark 工作流同步、将 OneNote 笔记导出为 GeminiSpark 可用格式，并演示常见自动化场景。

🎯 这是什么功能

将你的 OneNote 笔记本转变为 AI 可访问的知识库：

• 列出所有笔记本、分区和页面

• 读取页面内容 以进行分析和搜索

• 自然语言查询，例如“显示我的 DevOps 笔记”或“查找有关项目规划的页面”

• 安全的 OAuth 身份验证，使用 Microsoft Graph API

• 可靠的错误处理，提供详细调试信息

✨ 为什么选择这个实现

与其他 OneNote MCP 服务器不同，此实现：

• ✅ 真实可用 - 经过真实 OneNote 数据的广泛测试

• ✅ 功能完整 - 实现了所有核心 OneNote 操作

• ✅ 身份验证稳健 - 两步设备流可处理边缘情况

• ✅ 生产就绪 - 合适的错误处理和日志记录

• ✅ 易于设置 - 为非技术用户提供详细说明

🚀 快速开始

先决条件

• Python 3.10+

• uv 包管理器（推荐）或 pip

• Google Gemini 账户

• Microsoft Azure 账户（免费）

1. 安装 uv（如果你还没有）

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# or with Homebrew
brew install uv

2. 克隆并设置

git clone https://github.com/yourusername/onenote-mcp-server.git
cd onenote-mcp-server

# Create virtual environment and install dependencies
uv sync

3. Azure 应用注册

你需要创建一个 Azure 应用来访问 OneNote。别担心，它完全免费，只需 5 分钟：

1. 前往 Azure Portal（使用你的 Microsoft 账户登录）

2. 导航到 Azure Active Directory → 应用注册 → 新注册

3. 填写表单：

   • 名称：“OneNote MCP Server”（或你喜欢的任何名称）

   • 支持的账户类型：“任何组织目录中的账户及个人 Microsoft 账户”

4. 单击 注册

5. 复制应用程序（客户端）ID - 你会用到它！

4. 添加权限

仍然在你的 Azure 应用中：

1. 转到 API 权限 → 添加权限

2. 选择 Microsoft Graph → 委派权限

3. 添加这些权限：

   • Notes.Read - 读取 OneNote 笔记本

   • Notes.ReadWrite - 创建/修改 OneNote 内容（可选但推荐）

   • User.Read - 读取用户配置文件

   • Offline.access - 允许刷新令牌访问

4. 单击“授予管理员同意”（顶部的按钮）

5. 转到“清单” -> 将 signInAudience 更新为 AzureADandPersonalMicrosoftAccount，并将 requestedAccessTokenVersion 更新为 2，然后保存。

5. 生成 Azure 刷新令牌（一次性操作）

• 在 refresh_token.py 文件中更新 Azure 客户端 ID，然后在命令行中运行它。

• 浏览器窗口将打开。使用你的 Microsoft ID 登录。

• 成功登录后，命令行中会生成令牌。

6. 在云/本地部署 MCP 服务器

• 例如，对于 Google Cloud 部署，运行以下命令。

  gcloud run deploy onenote-mcp-server --source . --region us-central1
  --set-env-vars="AZURE_REFRESH_TOKEN=YOUR_AZURE_REFRESH_TOKEN,AZURE_CLIENT_ID=YOUR_ACTUAL_CLIENT_ID"
  --allow-unauthenticated
  

• 部署后，将生成 MCP 服务器 URL。

7. 在 Gemini Spark 中设置自定义已连接应用

• 点击“已连接应用”

• 填写 MCP 服务器 URL/sse（别忘了在 URL 末尾添加 /sse）

• 在高级设置中 -> 填写 Azure 客户端 ID

• 点击“复制重定向 URI”，然后前往 Azure Portal --> Azure 客户端应用 --> 身份验证 --> 重定向 URI --> 添加 URI --> Web --> 粘贴复制的链接 --> 删除任何其他重定向 URI

• 在“已连接应用”对话框上 -> 点击“下一步”并按照屏幕提示操作。

• Onenote Mcp server 将在“已连接应用”屏幕中创建。

使用方法

设置好已连接应用后，请在 Gemini Spark 中尝试以下任务：

List my OneNote notebooks
Show me sections in my Work notebook  
What pages are in my Ideas section?
Read the content of my "Project Plan" page

🛠 故障排除

Gemini Spark 的“已连接应用”屏幕中显示“没有可用工具”

• 确保你从屏幕复制了重定向 URI，并正确更新到 Microsoft Azure 应用上。

• 检查你的 MCP 服务器云部署是否启用了未认证访问。

• 验证 uv 是否已安装：uv --version

身份验证问题

• Safari OAuth 问题：Safari 可能无法正确处理 Microsoft 的 OAuth 重定向 - 请改用 Firefox 或 Chrome

• “nativeclient”提示：这是 Microsoft OAuth 的正常行为，但如果它阻止了身份验证，请尝试其他浏览器

• 推荐浏览器：Firefox（已验证可用）、Chrome 或 Edge 以获得最佳兼容性

“找不到命令”错误

• 确保 uv 在你的 PATH 中

• 替代方法：在配置中将 "uv" 替换为 "python"，并使用 Python 解释器的完整路径

权限被拒绝错误

• 检查项目目录中的文件权限

🏗 开发

项目结构

onenote-mcp-server/
├── onenote_mcp_server.py      # Main server implementation
├── pyproject.toml             # Dependencies and metadata
├── refresh_token.py           # Generate Refresh Token
├── README.md                  # This file
├── LICENSE                    # MIT License
└── .gitignore                 # Git ignore rules

主要特性

• 完整的 Graph API 集成：支持所有 OneNote 操作

• 稳健的错误处理：详细的日志记录和优雅的失败处理

• FastMCP 框架：干净、可维护的代码结构

• 环境变量配置：安全的凭据处理

添加新功能

该服务器基于 FastMCP 构建，可轻松添加新工具：

if method == "tools/list":
                    await custom_send({"type": "http.response.start", "status": 200, "headers": [(b"content-type", b"application/json")]})
                    tools = [
  
    # Your implementation here
    return 

🤝 贡献

欢迎贡献力量！请：

1. Fork 此仓库

2. 创建功能分支

3. 为新功能添加测试

4. 提交拉取请求

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• 使用 FastMCP 框架构建

• 使用 Microsoft Graph API 访问 OneNote

• 受 purpleslurple 出色工作的启发

⚠️ 重要说明

• 此服务器只读取/写入你已有权限访问的数据

• 你的 Azure 应用凭据将保留在本地机器上

• 所有身份验证均直接在你与 Microsoft 之间进行

• 不会向第三方发送任何数据

用 ❤️ 为 Gemini Spark + OneNote 社区构建

将你的 OneNote 变成 AI 可访问的知识库！