Skip to main content
Glama
OneNote MCP Server

OneNote MCP Server

by umangnine

Microsoft OneNote Model Context Protocol (MCP) Server

Platform: Windows Python: 3.12+ FastMCP Office: OneNote Desktop

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)   β”‚
                   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  1. Offline Reading Engine (pyOneNote):

    • Parses local .one binary backup files in %LOCALAPPDATA%\Microsoft\OneNote\16.0\Backup\.

    • Blazing-fast full-text search across all notebooks and sections without querying the UI.

  2. 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.

  3. 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.

  4. 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

  1. Operating System: Windows 10 or Windows 11 (64-bit).

  2. 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.

  3. Python: Python 3.12+ installed (or uv).

  4. 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 sync

Option 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:

  1. Clone this repository to any folder on your Windows machine:

    git clone https://github.com/umangnine/onenote-mcp.git
    cd onenote-mcp
  2. Open your AI coding assistant inside this directory.

  3. 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.cmd

Expected 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 list

3. 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

list_live_notebooks

None

COM

Lists all notebooks and sections currently open and active in the OneNote desktop GUI.

list_live_pages

notebook_name, section_name

COM

Lists all page titles and their persistent OneNote page IDs ({GUID}{version}{id}).

create_page

notebook_name, section_name, title, content

COM

Creates a brand-new page with rich HTML formatting in < 1.0 second. Auto-creates the section if it doesn't exist.

append_to_page

page_id, content

COM

Appends an additional rich HTML outline block to the bottom of an existing page.

update_page_content

page_id, content

COM

Replaces the entire outline content of an existing page with new rich HTML.

read_live_page

page_id (or notebook_name, section_name, page_title), raw_xml

COM

Reads a live page and converts headings, tables, and nested sub-bullets into structured Markdown. Set raw_xml=true to retrieve raw OneNote XML.

list_notebooks

None

Backup

Lists local notebook backup folders and section counts.

list_sections

notebook_name

Backup

Lists sections in a backup notebook with their file sizes.

list_all_sections

None

Backup

Recursively lists all notebooks and sections found in backup storage.

read_section

notebook_name, section_name

Backup

Extracts all plaintext from a section backup (.one file).

search_notes

query

Backup

Full-text keyword search across all local backup files with 160-character context snippets.

get_notebook_summary

notebook_name

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

<h1>Title</h1>

<one:OE><one:T>

24.0pt bold text in Navy (#003366) with spacing

<h2>Heading</h2>

<one:OE><one:T>

18.0pt bold text in Blue (#004080) with spacing

<h3>Subhead</h3>

<one:OE><one:T>

14.0pt bold text in Slate (#0059B3) with spacing

<p>Text</p>

<one:OE><one:T>

12.0pt clean body text

<ul><li>...</li></ul>

<one:List><one:Bullet>

Native OneNote bullet points

<ul><li>Parent<ul><li>Child</li></ul></li></ul>

Nested <one:OEChildren>

True hierarchical sub-bullet indentation

<hr /> or <br /><hr /><br />

<one:OE><one:T>

Formatted divider (──────────────────────────────────────────────────) with vertical padding

<table bordersVisible="true">

<one:Table>

Native OneNote grid table with border lines

<th>Header</th>

<one:Cell shadingColor="#EBF2FA">

Table header cell with soft blue background shading

<pre><code>code</code></pre>

<one:Table> single cell

Monospace code block in Consolas font with shaded background (#F5F7FA)

<b>, <i>, <u>, <span>

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:

    1. Click "Start normally" on the OneNote desktop window.

    2. Never blindly kill all ONENOTE processes. 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_xml parser 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 ...). Both server.py and scripts/read_onenote_page.ps1 enforce -STA by default.


πŸ“œ License & Attribution

  • Project Lead & Author: Umang Kathiyara (@umangnine)

  • License: MIT License β€” free and open-source for personal and commercial use.

Available Tools

12 tools
append_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

    A3.5/5.0

    Scored across 12 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables 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.
      10
      4
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Connects 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