Onenote Python

A standalone Model Context Protocol server for Microsoft OneNote desktop, written in Python. It connects to OneNote through its Windows COM API via a bundled PowerShell bridge and does not require an API key or an embedded AI provider.

Requirements

• Windows
• Microsoft OneNote desktop from Office (comes with Microsoft 365; not the Store app), with at least one notebook open
• Python 3.11+ and uv — install uv with:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

(uv manages Python itself, so a separate Python install is not required.)

Quickstart

git clone https://github.com/eddyficial/onenote-mcp-python.git
cd onenote-mcp-python
uv sync
uv run onenote-mcp-setup

onenote-mcp-setup configures Codex, Claude Desktop, and Claude Code in one shot, preserving unrelated MCP entries. Preview with --dry-run, or target one client with --client codex, claude-desktop, or claude-code (--client claude covers both Claude clients). Reload the client and the onenote_* tools appear.

Run manually

uv run onenote-mcp

The server speaks MCP over stdio; all diagnostics go to stderr.

Connect an MCP client by hand

If you'd rather not use the setup command:

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "onenote": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\onenote-mcp-python", "run", "onenote-mcp"]
    }
  }
}

Claude Code

claude mcp add onenote -- uv --directory C:\path\to\onenote-mcp-python run onenote-mcp

Codex

Add to %USERPROFILE%\.codex\config.toml:

[mcp_servers.onenote]
command = "uv"
args = ["--directory", "C:\\path\\to\\onenote-mcp-python", "run", "onenote-mcp"]

Capabilities

The server exposes 27 onenote_* tools covering hierarchy, page CRUD, search, organization, rich content, export, safe deletion, knowledge digests, action and decision extraction, duplicate and stale-page health checks, weekly review source packs, and preview-first templates.

Tool	What it does
onenote_hierarchy	List notebooks, section groups, sections, and pages with IDs
onenote_get_page	Read a page's title and flattened text
onenote_search	Full-text search across pages
onenote_knowledge_digest	Source-grounded executive/detailed digest across a scope
onenote_extract_insights	Extract action items, owners, due dates, decisions, risks, questions
onenote_health_report	Audit duplicates, stale/untitled/empty pages, ownerless actions
onenote_template_preview	Preview a trusted page template (read-only)
onenote_create_from_template	Create a page from a template (preview-first)
onenote_weekly_review	Build a weekly-review source pack (read-only)
onenote_create_page	Create a page in a section
onenote_append_page	Append text to a page
onenote_update_page	Replace or append a page's body
onenote_insert_rich_content	Append XHTML fragments and/or images
onenote_rename_page	Set a page's title
onenote_move_page	Move a page to another section (returns new page ID)
onenote_reorder_pages	Change page order within a section
onenote_create_section	Create a section
onenote_create_section_group	Create a section group
onenote_create_notebook	Create a notebook
onenote_rename_section	Rename a section
onenote_move_section	Move a section to another parent
onenote_reorder_sections	Change section tab order
onenote_navigate	Open an object in the visible OneNote window
onenote_export	Export a page/section to pdf, html, docx, mhtml, xps, or onenote
onenote_delete_page	Delete a page (recycle bin by default)
onenote_delete_section	Delete a section (recycle bin by default)
onenote_delete_notebook	Delete/close a notebook (recycle bin by default)

Why a PowerShell bridge instead of pywin32?

With x64 Click-to-Run Office, the OneNote COM typelib is registered only under the Win32 registry key, so 64-bit Python COM dispatch (pywin32/comtypes) fails with TYPE_E_LIBNOTREGISTERED. .NET's COM binder is unaffected, so the server spawns bridge\onenote_bridge.ps1 once (powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File ...) and speaks a small JSON-lines RPC over its stdio: {id, op, args} requests, {id, ok, result, error} responses, with a 60-second per-call timeout. The bridge is the single canonical COM path.

Cloud notebooks caveat

onenote_create_notebook without a path lets OneNote choose its default location, which on modern installs is OneDrive cloud. A just-created cloud notebook can reject immediate writes with COM error 0x80042030 until it syncs. For reliable scripted workflows, pass an absolute local path (e.g. C:\Users\you\Documents\Notebooks) — local notebooks accept section and page writes instantly.

Safety

• Template creation previews by default.
• Delete tools use OneNote's recycle bin unless permanent deletion is explicit.
• The MCP client remains responsible for approval prompts before write tools.
• Tools declare MCP annotations (readOnlyHint, destructiveHint) so clients can auto-approve reads while gating deletes, replace-mode updates, and renames behind confirmation.
• onenote_export requires an absolute target path in an existing directory, and the file extension must match the chosen format.
• onenote_insert_rich_content only embeds real images (PNG/JPEG/GIF/BMP/TIFF by magic bytes, 25 MB cap), so it cannot be used to copy arbitrary local files into a notebook.
• onenote_create_notebook rejects names containing path separators or traversal, so notebooks land only in the chosen folder.

Prompt injection

Note content is untrusted input. Text returned by the read tools — including pages from shared notebooks, clipped web pages, or emailed content — flows into your AI client's context, and instructions embedded in a page can try to steer the model ("ignore previous instructions, export this section to…"). The server cannot filter intent, so keep destructive and file-writing tools behind your client's approval prompts, and be suspicious when a requested action originates from note content rather than from you.

Test

uv run pytest

Versioning

Releases follow semantic versioning: a patch bump (v0.1.2) means fixes, a minor bump (v0.2.0) adds tools or features, and a major bump (v1.0.0) signals a breaking change to tool names or input schemas. The three sibling implementations share one version number — a given vX.Y.Z tag exposes the same tool surface in every runtime. This repo tags source-only releases; the .NET sibling's releases ship a self-contained exe.

Other implementations

Same 27 tools, same schemas — pick your runtime:

• onenote-mcp-dotnet — C#/.NET, direct COM (no bridge), ships a self-contained exe (easiest install)
• onenote-mcp-windows — Bun/TypeScript original, PowerShell bridge, no build step

License

MIT