内容
# 本地 OneNote MCP
一个高性能的本地 Microsoft OneNote MCP 服务器，适用于 Windows。它通过本地 OneNote COM API 直接控制 OneNote 桌面应用程序——**无需 Azure、Microsoft Graph、API 密钥或在线 OAuth**。
---
## 设计与架构
- **仅限本地边界：** 所有操作直接通过本地 OneNote 桌面安装执行。数据永远不会离开您的计算机。
- **COM 优先工程：** 不直接操作二进制 `.one` 文件。所有写入和读取都利用 OneNote 的原生 COM 引擎，确保最大程度的数据完整性和同步兼容性。
- **安全执行桥：** 输入通过基于 JSON 的临时文件安全传递，完全避免 PowerShell 字符串插值或命令注入风险。
- **丰富的交互界面：** 提供笔记本、分区组、分区、页面、同步和原始 XML 操作的完整 CRUD 功能。
> **设计说明：** PowerShell 被用作可靠的 COM 桥，因为某些 Windows/Office 环境直接向 PowerShell 公开 OneNote COM 接口，而这些接口对于 Python 的传统自动化库不可用或受到限制。
---
## 需求
- **Windows 10 / 11**
- **Microsoft OneNote 桌面应用程序**（传统版本；非旧版 Windows 10 UWP 应用程序）
- **Python 3.11+**
- **Node.js & npm**（标准全局启动器所需）
- **OneMore 桌面插件**（可选 - 仅需启用富 Markdown 编译）
验证您的系统环境：
```powershell
node -v
npm -v
python --version
```
---
## 快速开始（推荐）
### 1. 安装全局启动器
打开 PowerShell 并运行：
```powershell
npm install -g github:Peteroooooooo/local-onenote-mcp
```
*(发布到 npm 注册表后，您将能够使用以下命令安装：`npm install -g local-onenote-mcp`)*
> ? **性能和启动提示：** 通过全局安装（`npm install -g`）或直接本地链接运行此服务器被高度推荐，而不是通过短暂的 `npx` 命令动态运行。这确保服务器 100% 离线运行，一致地解析实际物理路径，完美地缓存底层 Python 虚拟环境，并在 1 秒内启动，避免缓慢的 GitHub 网络请求和启动时的冗余软件包重新安装。
### 2. 配置您的 MCP 客户端
#### Claude 桌面版
将以下内容添加到您的 `%APPDATA%\Claude\claude_desktop_config.json`：
```json
{
"mcpServers": {
"local-onenote": {
"command": "local-onenote-mcp",
"env": {
"LOCAL_ONENOTE_MCP_TIMEOUT": "90",
"LOCAL_ONENOTE_MCP_MAX_TEXT_CHARS": "60000"
}
}
}
}
```
#### Codex / Cursor (TOML)
将以下内容添加到您的配置文件：
```toml
[mcp_servers.local-onenote]
type = "stdio"
command = "local-onenote-mcp"
startup_timeout_ms = 120000
[mcp_servers.local-onenote.env]
LOCAL_ONENOTE_MCP_TIMEOUT = "90"
LOCAL_ONENOTE_MCP_MAX_TEXT_CHARS = "60000"
```
*重启您的 MCP 客户端。首次执行时，启动器会自动创建本地 Python 虚拟环境，安装所需软件包，并托管_stdio 通道。*
---
## 替代安装选项
### 选项 A：现代 Python 工具链（无需 npm）
如果您更喜欢纯 Python 执行，您可以配置您的 MCP 客户端通过标准 Python 软件包运行器调用服务器。
#### 使用 `uvx`（超快，短暂执行）
```toml
[mcp_servers.local-onenote]
type = "stdio"
command = "uvx"
args = [
"--from",
"git+https://github.com/Peteroooooooo/local-onenote-mcp",
"local-onenote-mcp"
]
startup_timeout_ms = 120000
```
#### 使用 `pipx`（隔离用户空间 CLI）
```powershell
pipx install git+https://github.com/Peteroooooooo/local-onenote-mcp
```
然后配置：
```toml
[mcp_servers.local-onenote]
type = "stdio"
command = "local-onenote-mcp"
startup_timeout_ms = 120000
```
---
### 选项 B：本地克隆和主动开发
要贡献或从源代码运行服务器：
1. **克隆存储库：**
```powershell
git clone https://github.com/Peteroooooooo/local-onenote-mcp
cd local-onenote-mcp
```
2. **构建 Python 虚拟环境：**
```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
```
3. **配置您的客户端以使用本地开发版本：**
```json
{
"mcpServers": {
"local-onenote-dev": {
"command": "C:\\path\\to\\local-onenote-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "local_onenote_mcp.server"],
"env": {
"LOCAL_ONENOTE_MCP_TIMEOUT": "90",
"LOCAL_ONENOTE_MCP_MAX_TEXT_CHARS": "60000"
}
}
}
}
```
4. **验证本地配置：**
```powershell
.\.venv\Scripts\python.exe scripts\check_codex_config.py
```
---
## OneMore 和 Markdown 集成
> 💡 **关于可选性和功能的重要说明：**
> - **100% 可选：** [OneMore](https://github.com/stevencohn/OneMore) 桌面插件**不是**硬依赖项。没有它，服务器可以正常运行，允许完整的笔记本层次结构发现、搜索、页面读取、导出、导航和页面创建/修改，使用纯文本或原始 HTML。
> - **格式化功能：** 如果安装，它将解锁巨大的生产力提升。它绑定到 OneMore 的高性能 `.NET Markdig` 渲染管道。这允许 AI 代理使用**标准、干净的 Markdown**（包括粗体、斜体、代码片段、带有样式的项目符号/编号列表、标题和块引用）编写，并自动将其转换为**完美格式化的原生 OneNote 组件和结构化表格**。
服务器通过 Windows 注册表或标准程序路径直接查询和绑定到 OneMore 的原生 `Markdig.Signed.dll`：
- `C:\Program Files\River\OneMoreAddIn\Markdig.Signed.dll`
- `C:\Program Files (x86)\River\OneMoreAddIn\Markdig.Signed.dll`
如果安装在自定义位置，请在配置变量中指定路径：
```toml
[mcp_servers.local-onenote.env]
LOCAL_ONENOTE_MARKDIG_DLL = "C:\\path\\to\\Markdig.Signed.dll"
```
---
## API 和工具目录
服务器公开 30 多个综合端点，分为四个逻辑类别：
### 1. 发现和内容检查
* `health_check`：获取服务器版本、Python 位置和活动功能。
* `list_notebooks` / `list_sections` / `list_pages` / `list_hierarchy`：遍历实时 OneNote 结构。
* `get_page` / `get_page_text` / `get_page_xml`：以纯文本、解析的 JSON 或原始 XML 提取页面内容。
* `get_page_objects` / `get_binary_content`：查询和提取子元素（例如表格、图像、墨水或文件附件有效载荷）。
* `search_pages`：搜索实时文本。支持实时离线扫描（`include_unindexed=true`）或索引搜索。
### 2. 创建和结构编辑
* `open_hierarchy` / `create_notebook` / `create_section` / `create_section_group`
* `create_page`：通过 `plain`、`html` 或 `markdown` 创建格式化页面。
* `update_page_title` / `append_to_page` / `replace_page_body`
* `add_image_to_page`：添加本地图像。如果仅提供宽度或高度，则自动推断原生尺寸。
### 3. 文件和应用程序控制
* `publish_object`：导出任意笔记本、分区或页面到本地 PDF 文件。
* `navigate_to` / `navigate_to_url`：立即聚焦并跳转桌面 UI 到特定元素。
* `sync_hierarchy`：触发特定笔记本的后台或立即同步。
* `close_notebook` / `merge_sections` / `set_filing_location`
### 4. 原始低级控制
* `update_page_xml` / `update_hierarchy_xml`：对 OneNote 的原始底层 XML 架构执行直接、高性能的编辑。
> **标识符解析协议：**
> 查询文件夹或项目时，服务器按以下优先级顺序尝试解析标识符：
> 1. 确切的 OneNote 对象 GUID（推荐用于自动化）
> 2. 相对层次结构路径（例如，`Personal/Quick Notes/My Section`）
> 3. 唯一显示名称
---
## 验证和烟雾测试
在启动前确保所有配置并运行正常：
```powershell
# 1. 运行只读发现验证
.\.venv\Scripts\python.exe scripts\smoke_mcp.py
# 2. 运行完整的读写/搜索验证循环
.\.venv\Scripts\python.exe scripts\smoke_mcp.py --notebook "MyNotebook" --section "MyNotebook/General" --export-dir tmp
```
---
## 提示工程和 Markdown 示例
以下是可以动态生成的典型 Markdown 格式：
```markdown
# 项目启动检查清单
- **项目：** Triton Migration
- **目标日期：** 2026-07-01
## 立即任务
- 定义系统架构布局。
- 完成本地安全边界审查。
## 路线图和里程碑
| 里程碑 | 负责人 | 状态 |
| --- | --- | --- |
| Beta 部署 | 基础设施 | **进行中** |
| 生产切换 | 运营 | 待定 |
```
---
## 限制和边界
此服务器依赖于 Windows COM API。虽然它擅长处理本地/离线笔记本，速度超过 Microsoft Graph Cloud API，但它仅限于单用户本地上下文和 Windows 原生环境。
