# 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](https://docs.astral.sh/uv/) — install uv with:

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

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

## Quickstart

```powershell
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

```powershell
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`:

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

### Claude Code

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

### Codex

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

```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

```powershell
uv run pytest
```

## Versioning

Releases follow [semantic versioning](https://semver.org): 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](https://github.com/eddyficial/onenote-mcp-dotnet) — C#/.NET, direct COM (no bridge), ships a self-contained exe (easiest install)
- [onenote-mcp-windows](https://github.com/eddyficial/onenote-mcp-windows) — Bun/TypeScript original, PowerShell bridge, no build step

## License

MIT