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

1. Open Microsoft Entra App registrations in Azure Portal
2. Create (or select) an application
3. Add a redirect URI: http://localhost:3000/callback
4. Create a client secret
5. 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:

1. Print an OAuth authorization URL to stderr
2. Wait for you to open the URL in your browser
3. Receive the callback at localhost
4. Cache tokens locally for reuse and refresh

Transport Mode

This server uses STDIO transport exclusively.

Tools

The server exposes 16 tools for interacting with OneNote:

Resources

The server exposes 5 resources for direct data access:

Prompts

The server includes 3 prompt templates for common workflows:

Configuration Reference

* 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 .env

Running Locally

# Development mode (auto-reload)
pnpm dev

# Production build
pnpm build

# Production run
pnpm start

Debugging

# Run from source
pnpm inspect

# Run from built output
pnpm inspect:dist

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

Support

See SUPPORT.md.

License

MIT © Jacob Hartmann