A
licenseNot graded
qualityD
maintenanceEnables AI language models to interact with Microsoft OneNote via a standardized interface, supporting notebook and page management through natural language.
39 npm
27
MIT
onenote-mcp
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 list my notebooks"
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.
OneNote MCP Server
A Model Context Protocol (MCP) server for Microsoft OneNote, authenticated via OAuth. Provides full read/write access to notebooks, sections, and pages through 16 tools, 5 resources, and 3 prompt templates.
Quick Start
Prerequisites
Node.js v22 or higher
A Microsoft Entra app registration with OAuth enabled
Client ID and client secret for your app registration
Step 1: Register an OAuth App
Open Microsoft Entra App registrations in Azure Portal
Create (or select) an application
Add a redirect URI:
http://localhost:3000/callbackCreate a client secret
Copy Application (client) ID and client secret
Step 2: Configure Your MCP Client
Claude Desktop (Recommended)
Add to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"onenote": {
"command": "npx",
"args": ["-y", "onenote-mcp"],
"env": {
"ONENOTE_OAUTH_CLIENT_ID": "your-client-id",
"ONENOTE_OAUTH_CLIENT_SECRET": "your-client-secret"
}
}
}
}Claude Code (CLI)
{
"mcpServers": {
"onenote": {
"command": "npx",
"args": ["-y", "onenote-mcp"],
"env": {
"ONENOTE_OAUTH_CLIENT_ID": "your-client-id",
"ONENOTE_OAUTH_CLIENT_SECRET": "your-client-secret"
}
}
}
}Cursor
{
"mcpServers": {
"onenote": {
"command": "npx",
"args": ["-y", "onenote-mcp"],
"env": {
"ONENOTE_OAUTH_CLIENT_ID": "your-client-id",
"ONENOTE_OAUTH_CLIENT_SECRET": "your-client-secret"
}
}
}
}Step 3: First-Time Authorization
On first use, the server will:
Print an OAuth authorization URL to stderr
Wait for you to open the URL in your browser
Receive the callback at localhost
Cache tokens locally for reuse and refresh
Related MCP server: OneNote MCP Server
Transport Mode
This server uses STDIO transport exclusively.
Tools
The server exposes 16 tools for interacting with OneNote:
Tool | Description |
| List all notebooks accessible to the authenticated user |
| Get detailed information about a specific notebook |
| List section groups in a notebook or across all notebooks |
| Get details of a specific section group including its sections |
| List sections in a notebook, section group, or across all notebooks |
| Get detailed information about a specific section |
| Create a new section in a notebook or section group |
| List pages in a specific section |
| Get metadata for a specific page (title, timestamps, parent info) |
| Get the full HTML content of a page |
| Get a short text preview of a page (up to 300 characters) |
| Create a new page in a section with HTML content |
| Update page content using JSON patch commands |
| Permanently delete a page |
| Search pages by keyword across titles and content |
| Get the complete notebook/section-group/section tree in one call |
Resources
The server exposes 5 resources for direct data access:
Resource | URI | Description |
|
| List of all notebooks |
|
| A specific notebook with its sections and section groups |
|
| Sections in a specific notebook |
|
| Pages in a specific section |
|
| The HTML content of a specific page |
Prompts
The server includes 3 prompt templates for common workflows:
Prompt | Description |
| Fetch and summarize the content of a specific OneNote page |
| Guide through a search workflow across OneNote notes |
| Guide through creating a new page in the right notebook and section |
Configuration Reference
Variable | Required | Default | Description |
| Yes* | - | OAuth client ID |
| Yes* | - | OAuth client secret |
| No | - | Manual token override (bypasses OAuth) |
| No |
| OAuth tenant selector |
| No |
| OAuth callback URI |
| No |
| Space-delimited OAuth scopes |
| No | platform default | Token cache file path |
| No |
| OAuth authority base override |
| No |
| Graph API base override |
* Required unless ONENOTE_ACCESS_TOKEN is set.
Features
16 MCP tools for full OneNote read/write access (notebooks, sections, pages)
5 MCP resources for direct data access via URI templates
3 MCP prompt templates for common workflows (summarize, search, create)
OAuth authorization code flow with automatic token refresh
Secure token cache with platform-specific default locations
Microsoft Graph API client with error handling and pagination
Security hardening (CodeQL, dependency review, Scorecard, SBOM)
CI/CD with automated release and npm trusted publishing
Development
Setup
# Clone the repo
git clone https://github.com/jacob-hartmann/onenote-mcp.git
cd onenote-mcp
# Use Node.js 22
# (macOS/Linux nvm): nvm install && nvm use
# (Windows nvm-windows): nvm install 22 && nvm use 22
# Install dependencies
pnpm install
# Copy env template
cp .env.example .envRunning Locally
# Development mode (auto-reload)
pnpm dev
# Production build
pnpm build
# Production run
pnpm startDebugging
# Run from source
pnpm inspect
# Run from built output
pnpm inspect:distContributing
See CONTRIBUTING.md.
Security
See SECURITY.md.
Support
See SUPPORT.md.
License
MIT © Jacob Hartmann
Available Tools
16 toolscreate-pageCreate PageA
Create a new page in a OneNote section. The content should be provided as HTML. The HTML must be valid XHTML with a title in the tag. At minimum, provide a title; the body can be empty for a blank page.
Inputs: title (required), sectionId (required), content.
create-sectionCreate SectionA
Create a new section. Provide notebookId to create in a notebook, or sectionGroupId to create inside a section group. Exactly one parent must be specified. Section names must be unique within the same hierarchy level, max 50 characters, and cannot contain: ? * / : < > | & # ' % ~
Inputs: displayName (required), notebookId, sectionGroupId.
delete-pageDelete PageADestructiveIdempotent
Permanently delete a OneNote page. This action cannot be undone. The page is immediately and permanently removed.
Inputs: pageId (required).
get-notebookGet NotebookARead-onlyIdempotent
Get detailed information about a specific OneNote notebook by its ID, including its sections and section groups. Use list-notebooks first to find the notebook ID.
Inputs: notebookId (required).
get-notebook-hierarchyGet Notebook HierarchyARead-onlyIdempotent
Get the complete hierarchy of all notebooks, section groups, and sections. Returns a tree structure: Notebooks > Section Groups > Sections (recursively for nested section groups). This is the most efficient way to understand the user's OneNote organization.
Inputs: no named parameters.
get-pageGet PageARead-onlyIdempotent
Get metadata for a specific OneNote page by its ID. Returns title, timestamps, and parent info but NOT the page content. Use get-page-content to retrieve the actual HTML content.
Inputs: pageId (required).
get-page-contentGet Page ContentARead-onlyIdempotent
Get the full HTML content of a OneNote page. The content is returned as HTML which represents the page's text, images, tables, and formatting. Use includeIds=true if you plan to update the page afterward.
Inputs: pageId (required), includeIds.
get-page-previewGet Page PreviewARead-onlyIdempotent
Get a text preview of a OneNote page (up to 300 characters). Useful for quickly scanning page content without fetching the full HTML.
Inputs: pageId (required).
get-sectionGet SectionARead-onlyIdempotent
Get detailed information about a specific section by its ID, including its parent notebook.
Inputs: sectionId (required).
get-section-groupGet Section GroupARead-onlyIdempotent
Get detailed information about a specific section group, including its sections and nested section groups.
Inputs: sectionGroupId (required).
list-notebooksList NotebooksARead-onlyIdempotent
List all OneNote notebooks accessible to the authenticated user. Returns notebook names, IDs, and metadata. Use this to discover available notebooks before accessing sections or pages.
Inputs: no named parameters.
list-pagesList PagesARead-onlyIdempotent
List pages in a specific section. Returns page titles, IDs, and metadata. Always specify a sectionId to avoid errors on accounts with many sections.
Inputs: sectionId (required), top.
list-section-groupsList Section GroupsARead-onlyIdempotent
List section groups. When notebookId is provided, lists section groups in that notebook. Otherwise lists all section groups across all notebooks.
Inputs: notebookId.
list-sectionsList SectionsARead-onlyIdempotent
List sections. Provide notebookId to list sections in a notebook, sectionGroupId to list sections in a section group, or omit both to list all sections across all notebooks.
Inputs: notebookId, sectionGroupId.
search-pagesSearch PagesARead-onlyIdempotent
Search for OneNote pages by keyword. Searches page titles and content (including OCR text from images). Optionally scope the search to a specific section. Returns matching page metadata.
Inputs: query (required), top, sectionId.
update-pageUpdate PageA
Update the content of an existing OneNote page using JSON patch commands. Each patch specifies a target element, an action (append, insert, replace), and content. Before updating, use get-page-content with includeIds=true to get element IDs for targeting.
Inputs: pageId (required), patches (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A4.1/5.0
Scored across 16 tools
Disambiguation5/5
Each tool targets a distinct resource-action combination (e.g., get-page vs get-page-content vs get-page-preview) with clear descriptions that eliminate ambiguity. Slight overlap among page retrieval tools is resolved by specific content scopes.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern using lowercase and hyphens (e.g., create-page, list-sections, get-notebook-hierarchy). No mixing of styles like camelCase or underscores.
Tool Count4/5
16 tools is slightly above the typical 3-15 range but still reasonable for a OneNote API surface. Each tool serves a distinct purpose, though a few (like get-page, get-page-content, get-page-preview) could be merged without loss.
Completeness3/5
Covers core operations for pages (CRUD, search, preview) and sections (list, get, create), but notable gaps exist: no create/delete for notebooks or section groups, no delete for sections, and no update for structural resources. This may force agents to use workarounds.
Maintenance
ActivityInactive
ResponsivenessNo recent community issues
Related MCP Connectors
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Knowledge base MCP for AI agents on iknow.dev. Search, read, and maintain via OAuth.
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
Related MCP Servers
- AlicenseDqualityCmaintenanceEnables AI assistants to securely interact with Microsoft OneNote data through the Microsoft Graph API. It supports comprehensive management tasks including searching page content, creating and editing notes, and automating productivity workflows like daily note creation.204MIT
- FlicenseAqualityDmaintenanceEnables AI agents to read, create, and analyze Microsoft OneNote notebooks, sections, and pages, including automatic image text extraction via Claude Vision.71-
- AlicenseAqualityCmaintenanceMCP server that connects AI tools to Microsoft OneNote for Business via the Microsoft Graph API, enabling listing, creating, and updating notebooks, sections, and pages.6MIT