MCP Onenote

🚀 MCP OneNote Server

A Model Context Protocol (MCP) server for Microsoft OneNote, enabling AI agents like Claude Desktop to read, create, and analyze OneNote notebooks, sections, and pages — including automatically extracting content from images via Claude Vision.

🚀 Quick Start

This server allows AI agents to interact with Microsoft OneNote, offering functions such as listing, reading, creating, and image content extraction.

✨ Features

• 📒 List notebooks, sections, and pages.
• 📄 Read the HTML content of pages.
• 🖼️ Extract text from embedded images via Claude Vision (new!).
• ✏️ Create notebooks, sections, and pages.
• 🔐 Authenticate via Azure AD Device Code Flow.

📦 Installation

Step 1 — Clone the Project

git clone https://github.com/FRESHSK/mcp_onenote.git
cd mcp_onenote_01
npm install

Step 2 — Create an Azure AD App (One-time)

This step is to obtain a Client ID to access the Microsoft Graph API.

1. Go to Azure Portal - App Registrations.
2. Click "New registration".
3. Fill out the form:
   • Name: MCP OneNote
   • Supported account types: Choose the 3rd option (Multitenant + personal Microsoft accounts)
   • Redirect URI: Public client/native → http://localhost
   • Click Register
4. Enable public flows:
   • Left menu → Authentication
   • Scroll down → Advanced settings
   • Allow public client flows → Yes
   • Click Save
5. Copy the Application (client) ID from Overview.

Step 3 — Add Microsoft Graph API Permissions

After creating the Azure AD app, you need to grant the necessary permissions to access OneNote.

1. In the Azure Portal, go to your App Registration.
2. Left menu → API permissions
3. Click "Add a permission"
4. Choose Microsoft Graph
5. Choose Delegated permissions
6. Search for and check the following permissions:

7. Click "Add permissions"
8. Click "Grant admin consent for ..." (if you are an admin) and then confirm.

ℹ️ If you are not an admin, the permissions will be granted during the first login via Device Code Flow.

Expected result in Azure Portal:

✅ User.Read              (Delegated) - Granted
✅ Notes.Read             (Delegated) - Granted
✅ Notes.Create           (Delegated) - Granted
✅ Notes.ReadWrite        (Delegated) - Granted

Step 4 — Configure Environment Variables

cp .env.example .env

Edit .env:

MICROSOFT_CLIENT_ID=your-azure-client-id
MICROSOFT_TENANT_ID=common
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
TOKEN_CACHE_PATH=./token_cache.json

⚠️ Never commit the .env file — it is in .gitignore.

Step 5 — First Microsoft Authentication

The server needs a Microsoft token to access OneNote. Run this script once:

node debug_auth.js

You will see in the terminal:

To sign in, use a web browser to open the page
https://microsoft.com/devicelogin and enter the code XXXXXXXX

1. Open https://microsoft.com/devicelogin.
2. Enter the code displayed in the terminal.
3. Sign in with your Microsoft account.
4. A token_cache.json file will be created automatically.

✅ This step is only necessary once. The token renews automatically.

Step 6 — Configure Claude Desktop

Edit the claude_desktop_config.json file in Claude Desktop:

• Windows: C:\Users\<user>\AppData\Roaming\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "onenote": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\mcp_onenote_01\\server.js"
      ],
      "env": {
        "TOKEN_CACHE_PATH": "C:\\absolute\\path\\to\\mcp_onenote_01\\token_cache.json"
      }
    }
  }
}

⚠️ The absolute TOKEN_CACHE_PATH is important for Claude Desktop to find the correct token file.

Step 7 — Restart Claude Desktop

Close and restart Claude Desktop. The MCP OneNote will be available.

💻 Usage Examples

Tools Available

Image Extraction (Claude Vision)

When extract_images: true (default), the read_content tool:

1. Parses the HTML of the page.
2. Detects <img> tags pointing to the Graph API.
3. Fetches each image with the Microsoft Bearer token.
4. Sends the image to Claude Vision to extract the textual content.
5. Returns the text + the extracted content of each image.

To disable this feature:

read_content(pageId: "...", extract_images: false)

📚 Documentation

Project Structure

mcp_onenote_01/
├── server.js                   # Main MCP server
├── debug_auth.js               # Initial authentication script
├── .env                        # Environment variables (not committed)
├── .env.example                # Environment variable template
├── .gitignore                  # Files ignored by Git
├── claude_desktop_config.json  # Example Claude Desktop config
├── token_cache.json            # MSAL token cache (not committed)
└── package.json                # Node.js dependencies

Main Dependencies

🔧 Technical Details

Security

• The .env file containing keys is in .gitignore.
• The token_cache.json file containing Microsoft tokens is in .gitignore.
• Never commit API keys or tokens to GitHub.

Troubleshooting

The MCP does not respond in Claude Desktop? → Check the logs: AppData\Roaming\Claude\logs\mcp-server-onenote.log

The token expires and requires re-authentication? → Ensure that TOKEN_CACHE_PATH points to the correct absolute path in claude_desktop_config.json. → Restart node debug_auth.js to renew the token.

media_type error on images? → The code automatically normalizes to image/png if the type is not supported by the Anthropic API.

📄 License

MIT