Overview

This MCP (Model Context Protocol) server connects AI assistants to Microsoft OneNote via the Microsoft Graph API. It exposes read/write operations for OneNote notebooks, sections, and pages so models can fetch contextual notes, index OneNote content for retrieval-augmented generation (RAG), or create and update pages programmatically.

The server uses MSAL’s device code flow for authentication and caches tokens locally, enabling headless or containerized deployments. It’s implemented in TypeScript and packaged to run locally, in development mode, or inside Docker — making it easy to integrate with AI agents (for example, Claude or other MCP-capable assistants).

Features

Read notebooks, sections, and pages from OneNote
Create notebooks, sections, and HTML pages in OneNote
Convert page HTML into plain text for RAG-friendly embeddings
MSAL device-code authentication with token caching
Simple MCP tool endpoints that AI agents can call
Docker support for persistent authentication across runs

Installation / Configuration

Prerequisites:

Node.js >= 14
npm
Microsoft Azure account with a registered app and OneNote access

Azure app setup:

Register an application in the Azure Portal.
Add Microsoft Graph permissions:
- Notes.Read
- Notes.ReadWrite
Under Authentication: enable “Allow public client flows” (device code flow) and choose account types that fit your environment (personal + organizational recommended).
Copy the Application (client) ID for use in configuration.

Clone and install:

git clone https://github.com/rajvirtual/MCP-Servers.git
cd MCP-Servers/onenote
npm install

Environment: Create a .env.local file in the project root or set environment variables. Minimal example:

CLIENT_ID=your-azure-app-client-id
PORT=3000

Development and build:

# Development with hot-reload (if configured)
npm run dev

# Compile TypeScript
npm run build

# Run compiled server
npm start

Docker:

# create a data dir to persist device-code and token cache
mkdir -p data

# build image
docker build -t onenote-mcp-server .

# run container (mount data for token persistence)
docker run -d \
  --name onenote-mcp-server \
  -e CLIENT_ID=your-client-id \
  -v $(pwd)/data:/app/dist \
  onenote-mcp-server

To authenticate when running in Docker:

# read device code printed to mounted data directory
cat data/device-code.txt
# follow the URL and enter the code

Available Tools

This server exposes two primary MCP tools:

onenote-read — list or fetch content

Supported operations: list notebooks, list sections in a notebook, list pages in a section, fetch page content.
Useful for RAG pipelines: the tool can return HTML and converted plain text.

Parameters (examples):

Parameter	Type	Description
type	string	“read_content”
notebookId	string (optional)	ID to list sections for
sectionId	string (optional)	ID to list pages for
pageId	string (optional)	ID of a specific page to fetch
includeContent	boolean	Include page HTML/text (default: true)
includeMetadata	boolean	Include page metadata like created/modified (default: false)

onenote-create — create notebooks, sections, pages

Supported types: create_notebook, create_section, create_page
Pages accept HTML content; server converts/stores content via Graph API.

Parameters:

Parameter	Type	Description
type	string	“create_notebook” / “create_section” / “create_page”
title	string	Title for notebook/section/page
content	string (HTML)	Page content (for create_page)
parentId	string (optional)	Parent notebook or section ID

Use Cases

Context enrichment for AI agents: fetch notes relevant to a user query and feed into a model for summarization or question answering. Example: list pages in a meeting notes section and return plain-text content to the model for RAG retrieval.
Automated note creation: generate meeting notes or task summaries with an agent and create a formatted OneNote page with HTML. Example: agent creates a “Weekly Summary” page in a project section using create_page and HTML content.
Notebook organization tooling: automated scripts that create sections or notebooks for new projects and seed them with templates.

Authentication Flow & Storage

On first run the server triggers MSAL device code flow, writes the code and URL to device-code.txt, and prompts manual authentication.
After successful sign-in, tokens are cached into token-cache.json (in the project or mounted data directory).
Remove token-cache.json to force re-authentication.

Files persisted for authentication:

device-code.txt — contains device code + URL for first-time sign-in
token-cache.json — MSAL token cache used for subsequent runs

Troubleshooting

Authentication failed: delete token-cache.json and re-run to trigger device-code flow again.
Permission denied errors: verify Graph API scopes (Notes.Read, Notes.ReadWrite) and re-grant admin consent if required.
TypeScript/build errors: run npm run build to surface compilation issues.

Resources

GitHub: https://github.com/rajvirtual/MCP-Servers/tree/master/onenote
Microsoft Graph OneNote docs: https://docs.microsoft.com/graph/onenote
MSAL device code flow docs: https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code

This MCP server provides a lightweight bridge between AI assistants and OneNote, enabling practical automations and improved context retrieval from users’ existing notes.

OneNote MCP Server for Microsoft Graph