OneNote MCP (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.)

Related MCP server: OneNote MCP Server

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.

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