OneNote MCP Server
OneNote MCP Server lets AI assistants search/read local OneNote backups and read, create, append, update, and inspect live OneNote Desktop pages via Windows COM automation.
List local notebooks, sections, and all sections; summarize notebooks; read section text; full-text search across backup files with snippets.
List live notebooks, sections, and pages from the running OneNote desktop app, including persistent page IDs.
Create new rich-text OneNote pages, auto-creating sections when needed.
Append content to existing pages or replace existing page body content.
Read live pages as structured Markdown or raw OneNote XML.
Convert semantic HTML into native OneNote XML: headings, paragraphs, lists, nested sub-bullets, tables, code blocks, dividers, and inline bold/italic/underline/color styling.
Enforce consistent typography such as minimum body font size and styled headings.
Work without cloud API tokens, Microsoft Graph registrations, or Azure credentials by using local
.onebackup parsing and live COM automation.Requires Windows and OneNote Desktop; the UWP OneNote for Windows 10 is not supported.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OneNote MCP Server search my notes for meeting minutes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Microsoft OneNote Model Context Protocol (MCP) Server
A high-performance, enterprise-grade Model Context Protocol (MCP) server providing AI coding assistants (Google Antigravity, Claude Code, Claude Desktop, Cursor) with full bi-directional integration into Microsoft OneNote Desktop on Windows.
Author: Umang Kathiyara (
@umangnine)
π Key Architecture & Capabilities
The server employs an intelligent dual-engine architecture requiring zero cloud API tokens, zero Microsoft Graph registrations, and zero Azure tenant credentials:
ββββββββββββββββββββββββββ
β AI Assistant Client β
β (Antigravity / Claude) β
βββββββββββββ¬βββββββββββββ
β MCP stdio
βΌ
ββββββββββββββββββββββββββ
β OneNote FastMCP Server β
β (server.py) β
βββββββ¬βββββββββββββ¬ββββββ
β β
Offline Reading Engine β β Live Real-time Engine
(Zero latency backups) β β (Active desktop automation)
βΌ βΌ
ββββββββββββββββββββββββ ββββββββββββββββββββββββ
β pyOneNote β β Windows COM (STA PS) β
β (.one binary parser) β β(OneNote.Application)β
ββββββββββββ¬ββββββββββββ ββββββββββββ¬ββββββββββββ
βΌ βΌ
ββββββββββββββββββββββββ ββββββββββββββββββββββββ
β Local Backup Storage β β OneNote Desktop GUI β
β (%LOCALAPPDATA%\...) β β (Active Notebooks) β
ββββββββββββββββββββββββ ββββββββββββββββββββββββOffline Reading Engine (
pyOneNote):Parses local
.onebinary backup files in%LOCALAPPDATA%\Microsoft\OneNote\16.0\Backup\.Blazing-fast full-text search across all notebooks and sections without querying the UI.
Live Automation Engine (Windows COM
OneNote.Application):Automates the running OneNote desktop application in real-time.
Creates and updates pages with native OneNote XML DOM elements in < 1.0 second.
Rich Text & High-Fidelity Typography Engine:
Automatically converts semantic HTML (
h1-h6,p,ul/ol/li,pre/code,table,hr,br,span,b,i) into structured<one:OE>elements.Enforces minimum 12.0pt font size across body content to eliminate unstyled, squinty text.
Preserves true hierarchical sub-bullet indentation using native
<one:OEChildren>nesting.Renders native grid tables (
<one:Table bordersVisible="true">) with styled headers and automatic column width calculation.Generates clean, styled horizontal dividers (
ββββββββββββββββββββββββββββββββββββββββββββββββββ) with vertical padding.
Resilient Process & Connection Governance:
Selectively cleans up headless background zombie processes (
MainWindowHandle == 0) while guarding visible desktop UI windows.Enforces Single-Threaded Apartment (STA) PowerShell execution.
Related MCP server: MCP OneNote Server
π Repository Structure
onenote-mcp/
βββ server.py # Polished FastMCP OneNote server implementation
βββ pyproject.toml # Modern Python project configuration
βββ uv.lock # Deterministic dependency lockfile
βββ .python-version # Target Python version (3.12)
βββ .gitignore # Git exclusion rules
βββ LICENSE # MIT open-source license
βββ README.md # Comprehensive setup & operations guide
βββ SETUP_PROMPT.md # One-shot setup prompt for AI coding assistants
βββ setup_mcp.cmd # One-click automated setup launcher for Windows
βββ test_connection.cmd # One-click environment diagnostic launcher
βββ schemas/ # MCP tool JSON schema declarations
β βββ list_live_notebooks.json
β βββ list_live_pages.json
β βββ create_page.json
β βββ append_to_page.json
β βββ update_page_content.json
β βββ read_live_page.json
β βββ list_notebooks.json
β βββ list_sections.json
β βββ list_all_sections.json
β βββ read_section.json
β βββ search_notes.json
β βββ get_notebook_summary.json
βββ scripts/ # Standalone PowerShell diagnostic & utility scripts
β βββ setup_mcp.ps1 # Automated setup script (venv, schemas, skills, diagnostics)
β βββ test_connection.ps1 # Diagnostic connection probe for COM and backup paths
β βββ read_onenote_page.ps1 # Standalone CLI reader for live OneNote pages
βββ skills/ # Agent Skill package for AI assistants
βββ onenote-mcp/
βββ SKILL.md # Core skill workflow & formatting rules
βββ references/
β βββ mcp-server-reference.md
β βββ onenote-xml-and-formatting.md
β βββ page-parsing-and-reading.md
βββ scripts/
βββ read_onenote_page.ps1π οΈ System Prerequisites
Operating System: Windows 10 or Windows 11 (64-bit).
Microsoft OneNote Desktop:
Microsoft 365, Office 2021, Office 2019, or Office 2016 desktop edition.
Note: The discontinued "OneNote for Windows 10" (UWP app from the Microsoft Store) does NOT provide the COM Automation API. The desktop version must be installed.
Python: Python 3.12+ installed (or
uv).OneNote Backups Enabled:
Open OneNote Desktop.
Navigate to: File β Options β Save & Backup.
Ensure the backup path points to
%LOCALAPPDATA%\Microsoft\OneNote\16.0\Backup(default).Click Back Up All Notebooks Now to initialize the backup cache for offline search.
π Setup & Installation on Windows
Option 1: Fast Setup using uv (Recommended)
uv provides lightning-fast, reproducible virtual environment setup:
# 1. Clone the repository
git clone https://github.com/umangnine/onenote-mcp.git
cd onenote-mcp
# 2. Sync virtual environment and dependencies in one step
uv syncOption 2: Standard Python pip Setup
# 1. Clone the repository
git clone https://github.com/umangnine/onenote-mcp.git
cd onenote-mcp
# 2. Create virtual environment
python -m venv .venv
# 3. Activate virtual environment
.\.venv\Scripts\Activate.ps1
# 4. Install dependencies
pip install "mcp[cli]" pyOneNoteπ€ One-Shot AI Agent Setup Prompt (Fastest Setup)
If you use Google Antigravity, Claude Code, Cursor, or Windsurf, you can set up everything in one shot:
Clone this repository to any folder on your Windows machine:
git clone https://github.com/umangnine/onenote-mcp.git cd onenote-mcpOpen your AI coding assistant inside this directory.
Provide the ready-to-use prompt from
SETUP_PROMPT.md. Your AI agent will automatically create the virtual environment, install dependencies, register the MCP server, copy tool schemas and skills, and run the verification suite.
β‘ Automated One-Click Setup Script
Prefer running a script directly? We provide an automated setup script that handles environment creation, dependency synchronization, MCP registration, schema installation, and diagnostics:
# In PowerShell:
powershell -ExecutionPolicy Bypass -File .\scripts\setup_mcp.ps1
# Or simply double-click / run the Windows batch launcher:
.\setup_mcp.cmdπ§ͺ Verifying the Environment
Verify your OneNote COM automation and backup discovery anytime using the diagnostics tool:
# Option A: PowerShell
powershell -ExecutionPolicy Bypass -File .\scripts\test_connection.ps1
# Option B: One-click launcher (bypasses PowerShell ExecutionPolicy restrictions)
.\test_connection.cmdExpected output:
============================================================
Microsoft OneNote MCP Environment Diagnostics Tool
============================================================
[OK] PowerShell Apartment State: STA (Required for OneNote COM)
[OK] OneNote desktop UI process is running (PID: 12345)
Testing OneNote COM API connection...
[OK] COM GetHierarchy succeeded! Found 3 active notebook(s).
- Notebook: Notes-2026
* Section: Update-Notes-26
* Section: Work-Notes
Checking OneNote local backup files...
[OK] Backup directory found: C:\Users\...\AppData\Local\Microsoft\OneNote\16.0\Backup
[OK] Discovered 35 backup (.one) file(s) for offline reading.
============================================================
Diagnostics Complete: Environment is 100% HEALTHY! π
============================================================βοΈ Manual Configuration for AI Clients
If you prefer to configure your AI assistant manually rather than using setup_mcp.cmd:
1. Google Antigravity IDE
Open %USERPROFILE%\.gemini\antigravity\mcp_config.json and register the onenote server (replace <path-to-repo> with your absolute directory, e.g. C:\\Projects\\onenote-mcp):
{
"mcpServers": {
"onenote": {
"command": "<path-to-repo>\\.venv\\Scripts\\python.exe",
"args": [
"<path-to-repo>\\server.py"
],
"env": {
"ONENOTE_BACKUP_DIR": "%LOCALAPPDATA%\\Microsoft\\OneNote\\16.0\\Backup"
}
}
}
}Tip: Copy all JSON files from .\schemas\ to %USERPROFILE%\.gemini\antigravity\mcp\onenote\ so the IDE eagerly exposes lazy schemas, and copy .\skills\onenote-mcp\ to %USERPROFILE%\.gemini\config\skills\onenote-mcp\.
2. Claude Code CLI
Inside your cloned repository directory, run:
claude mcp add --transport stdio onenote -- "$PWD\.venv\Scripts\python.exe" "$PWD\server.py"Verify status:
claude mcp list3. Claude Desktop / Cursor
Edit %APPDATA%\Claude\claude_desktop_config.json (or .cursor/mcp.json):
{
"mcpServers": {
"onenote": {
"command": "<path-to-repo>\\.venv\\Scripts\\python.exe",
"args": [
"<path-to-repo>\\server.py"
],
"env": {
"ONENOTE_BACKUP_DIR": "%LOCALAPPDATA%\\Microsoft\\OneNote\\16.0\\Backup"
}
}
}
}π MCP Tool Reference
Tool Name | Parameters | Engine | Purpose & Description |
| None | COM | Lists all notebooks and sections currently open and active in the OneNote desktop GUI. |
|
| COM | Lists all page titles and their persistent OneNote page IDs ( |
|
| COM | Creates a brand-new page with rich HTML formatting in < 1.0 second. Auto-creates the section if it doesn't exist. |
|
| COM | Appends an additional rich HTML outline block to the bottom of an existing page. |
|
| COM | Replaces the entire outline content of an existing page with new rich HTML. |
|
| COM | Reads a live page and converts headings, tables, and nested sub-bullets into structured Markdown. Set |
| None | Backup | Lists local notebook backup folders and section counts. |
|
| Backup | Lists sections in a backup notebook with their file sizes. |
| None | Backup | Recursively lists all notebooks and sections found in backup storage. |
|
| Backup | Extracts all plaintext from a section backup ( |
|
| Backup | Full-text keyword search across all local backup files with 160-character context snippets. |
|
| Backup | Returns section outlines with ~200-character content previews. |
π¨ HTML Formatting & Typography Standards
When sending content to create_page or append_to_page, use standard HTML tags. The server automatically maps them to Microsoft OneNote XML:
1. Supported Tags & Visual Mapping
HTML Element | OneNote XML Translation | Visual Output in OneNote |
|
| 24.0pt bold text in Navy ( |
|
| 18.0pt bold text in Blue ( |
|
| 14.0pt bold text in Slate ( |
|
| 12.0pt clean body text |
|
| Native OneNote bullet points |
| Nested | True hierarchical sub-bullet indentation |
|
| Formatted divider ( |
|
| Native OneNote grid table with border lines |
|
| Table header cell with soft blue background shading |
|
| Monospace code block in Consolas font with shaded background ( |
| CDATA inline styles | Bold, italic, underline, custom color styling |
2. Daily Work Report Architecture Template
For consistent engineering notes, sprint logs, and daily work reports:
<h2>π§ Service Architecture - Backend/API</h2>
<p><span style="font-family:Consolas, monospace;font-size:9.5pt;color:#666666;">my-project Β· branch: main</span></p>
<p><b>2026-09-30 (Wednesday)</b></p>
<ul>
<li><b>Feature Area Title:</b>
<ul>
<li>Technical description bullet point 1</li>
<li>Technical description bullet point 2</li>
</ul>
</li>
<li><b>Impact:</b>
<ul>
<li>β
Measurable outcome 1</li>
<li>β
Measurable outcome 2</li>
</ul>
</li>
</ul>
<br /><hr /><br />
<h2>π₯οΈ Frontend Web Application</h2>
<p><span style="font-family:Consolas, monospace;font-size:9.5pt;color:#666666;">web-client Β· branch: main</span></p>
<p><b>2026-09-30 (Wednesday)</b></p>
<ul>
<li><b>UI Enhancements:</b>
<ul>
<li>Implemented responsive settings drawer</li>
</ul>
</li>
</ul>
<br /><hr /><br />
<h2>π Summary Metrics</h2>
<table bordersVisible="true">
<tr>
<th style="background-color:#EBF2FA;">Metric / Dimension</th>
<th style="background-color:#EBF2FA;">Value / Outcome</th>
</tr>
<tr><td><b>Working Day</b></td><td>Wednesday, 30 September, 2026</td></tr>
<tr><td><b>Total Commits</b></td><td>7</td></tr>
<tr><td><b>Key Deliverables</b></td><td>Dynamic labels, Storage permissions, Webhook protection</td></tr>
<tr><td><b>Repos Active</b></td><td>2</td></tr>
</table>
<p><i>Report generated with OneNote MCP</i></p>π§ Troubleshooting & Recovery Discipline
1. OneNote Desktop Shows Safe Mode Prompt ("Start normally")
Symptom: OneNote hangs on startup or displays a modal asking to Start normally, Delete notebook cache, or Delete settings.
Cause: OneNote processes were forcefully killed (
Stop-Process -Force) while holding file locks.Remedy:
Click "Start normally" on the OneNote desktop window.
Never blindly kill all
ONENOTEprocesses. The server's built-in_cleanup_orphan_onenote()function selectively terminates only headless background instances (MainWindowHandle == 0), leaving visible user windows untouched.
2. COM Error 0x80042009 (UpdatePageContent failed)
Cause: Passing unescaped block HTML tags (
<div>,<p>,<table>) directly inside a single<one:T><![CDATA[...]]></one:T>.Remedy: The server's
_html_to_onenote_xmlparser automatically decomposes complex HTML into separate<one:OE>elements. Use standard semantic HTML tags and let the parser structure the XML.
3. KERNELBASE.dll Crash (0xc06d007e)
Cause: Inserting literal
<br/>tags inside OneNote CDATA text nodes.Remedy: In OneNote XML, line breaks between separate blocks must be represented as distinct
<one:OE>elements or spacers, never unescaped HTML tags in CDATA.
4. PowerShell Apartment State Error
Cause: PowerShell running in Multi-Threaded Apartment (MTA) mode.
Remedy: All COM calls must execute in Single-Threaded Apartment mode (
powershell.exe -STA ...). Bothserver.pyandscripts/read_onenote_page.ps1enforce-STAby default.
π License & Attribution
Project Lead & Author: Umang Kathiyara (
@umangnine)License: MIT License β free and open-source for personal and commercial use.
Available Tools
12 toolsappend_to_pageA
Append content to an existing OneNote page.
The content is added as a new outline block at the bottom of the page.
Supports full rich HTML formatting (h1-h6, p, ul/ol/li, b, i, u, span, hr, br).
Args:
page_id: The page ID (from list_live_pages).
content: The content to append as HTML.
Inputs: content (required), page_id (required). Returns: result
create_pageA
Create a new page in a OneNote notebook section.
The content is written as HTML with full rich-text support.
Supported tags: h1-h6 (headings with auto font sizing), p, ul/ol/li (lists
with bullets/numbers), b/strong (bold), i/em (italic), u (underline),
span (with style), a (links), hr (horizontal rule), br, table/tr/td/th.
Headings get automatic font sizes: h1=24pt, h2=18pt, h3=14pt, h4=13pt,
h5=12pt, h6=11pt. All body text is 11pt minimum.
Requires the OneNote desktop app to be installed.
Args:
notebook_name: Name of the notebook (from list_live_notebooks).
section_name: Name of the section within the notebook.
title: Title for the new page.
content: The page content as HTML.
Inputs: title (required), content (required), section_name (required), notebook_name (required). Returns: result
get_notebook_summaryC
Get a summary of a notebook: its sections and a preview of each section's content.
Args:
notebook_name: The name of the notebook.
Inputs: notebook_name (required). Returns: result
list_all_sectionsA
List ALL sections across ALL notebooks.
Useful for getting a complete overview of everything in your OneNote.
Inputs: no named parameters. Returns: result
list_live_notebooksA
List notebooks from the running OneNote app (live, not backup files).
This uses the OneNote COM API and shows the notebooks currently open in the OneNote desktop app, including their sections. Use this to find where to create new pages.
Inputs: no named parameters. Returns: result
list_live_pagesB
List pages in a section from the running OneNote app.
Use this to find page IDs for appending content to existing pages.
Args:
notebook_name: Name of the notebook.
section_name: Name of the section.
Inputs: section_name (required), notebook_name (required). Returns: result
list_notebooksA
List all locally available OneNote notebooks.
Shows notebook names and how many sections each one has.
Inputs: no named parameters. Returns: result
list_sectionsC
List all sections in a specific notebook.
Args:
notebook_name: The name of the notebook (from list_notebooks).
Inputs: notebook_name (required). Returns: result
read_live_pageA
Read full text, tables, and hierarchical sub-bullets from a live OneNote page as Markdown or raw XML.
Args:
page_id: The persistent OneNote page ID (e.g. from list_live_pages).
notebook_name: Optional notebook name if page_id is not provided.
section_name: Optional section name if page_id is not provided.
page_title: Optional substring of the page title to search for if page_id is not provided.
raw_xml: If True, returns the raw OneNote page XML instead of Markdown.
Inputs: page_id, raw_xml, page_title, section_name, +1 more. Returns: result
read_sectionA
Read all text content from a specific section of a notebook.
Args:
notebook_name: The name of the notebook.
section_name: The name of the section (from list_sections).
Inputs: section_name (required), notebook_name (required). Returns: result
search_notesA
Search for text across ALL notebooks and sections.
Searches through the text content of every section for the given query.
Returns matching sections with a snippet of the matched text.
Args:
query: The text to search for (case-insensitive).
Inputs: query (required). Returns: result
update_page_contentB
Replace the body content of an existing OneNote page with new HTML formatting.
Args:
page_id: The persistent OneNote page ID (from list_live_pages).
content: The new page content as HTML.
Inputs: content (required), page_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 12 tools
Most tools target distinct objects/actions, but there is overlap between local vs. live notebook/section/page listings, such as list_notebooks vs. list_live_notebooks and list_sections vs. list_all_sections. Descriptions clarify the live/local distinction, so an agent can usually choose correctly, but the boundaries are not perfectly crisp.
The set mostly follows a consistent snake_case verb_noun pattern (list_notebooks, read_section, create_page, update_page_content). Minor inconsistency comes from inserting 'live' in some names (read_live_page, list_live_pages, list_live_notebooks) while other local counterparts omit it.
Twelve tools is a well-scoped size for a OneNote server covering notebooks, sections, pages, reading, searching, and writing. Each tool has a plausible role, and the set is not bloated or too thin.
Core read/search/create/update page workflows are covered, but lifecycle operations are notably incomplete: there is no delete page/section/notebook, no rename or move/copy page, and no create notebook/section. These gaps will cause failures for common management requests.
Maintenance
Related MCP Connectors
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
Personal context for every AI: search, read, and write back to your private Markdown library.
Create, search, and update notes in an xNotepad AI notebook, with semantic search and AI Q&A.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables Claude to read and write to local Microsoft OneNote notebooks by parsing backup files and utilizing the OneNote COM API. It allows for searching notes, creating pages, and appending content without requiring Azure registration or API keys.104-
- FlicenseAqualityDmaintenanceEnables AI agents to read, create, and analyze Microsoft OneNote notebooks, sections, and pages, including automatic image text extraction via Claude Vision.71-
- AlicenseNot gradedqualityAmaintenanceConnects to Microsoft OneNote desktop via COM API, exposing 27 tools for hierarchy, page CRUD, search, rich content, export, health checks, and more. Enables natural-language control of OneNote without API keys or embedded AI providers.MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude to read local OneNote notebooks via the Windows desktop COM API, including text from pasted screenshots, while keeping all data on the machine.MIT