purpleslurple/onenote-mcp-server

OneNote MCP Server

A complete, robust Model Context Protocol (MCP) server for Microsoft OneNote integration with Claude Desktop. Access your entire OneNote knowledge base through natural language queries.

🎯 What This Does

Transform your OneNote notebooks into an AI-accessible knowledge base:

• List all your notebooks, sections, and pages
• Read page content for analysis and search
• Natural language queries like "Show me my DevOps notes" or "Find pages about project planning"
• Secure OAuth authentication with Microsoft Graph API
• Bulletproof error handling with detailed debugging

✨ Why This Implementation

Unlike other OneNote MCP servers, this one:

• ✅ Actually works - tested extensively with real OneNote data
• ✅ Complete functionality - all core OneNote operations implemented
• ✅ Robust authentication - two-step device flow that handles edge cases
• ✅ Production ready - proper error handling and logging
• ✅ Easy setup - detailed instructions for non-technical users

🚀 Quick Start

Prerequisites

• Python 3.10+
• uv package manager (recommended) or pip
• Claude Desktop
• Microsoft Azure account (free)

1. Install uv (if you don't have it)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# or with Homebrew
brew install uv

2. Clone and Setup

git clone https://github.com/yourusername/onenote-mcp-server.git
cd onenote-mcp-server

# Create virtual environment and install dependencies
uv sync

3. Azure App Registration

You need to create an Azure app to access OneNote. Don't worry, it's free and takes 5 minutes:

1. Go to Azure Portal (sign in with your Microsoft account)
2. Navigate to Azure Active Directory → App registrations → New registration
3. Fill out the form:
   • Name: "OneNote MCP Server" (or whatever you like)
   • Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"
   • Redirect URI: Select "Public client/native" and enter: https://login.microsoftonline.com/common/oauth2/nativeclient
4. Click Register
5. Copy the Application (client) ID - you'll need this!

4. Add Permissions

Still in your Azure app:

1. Go to API permissions → Add a permission
2. Select Microsoft Graph → Delegated permissions
3. Add these permissions:
   • Notes.Read - Read OneNote notebooks
   • Notes.ReadWrite - Create/modify OneNote content (optional but recommended)
   • User.Read - Read user profile
4. Click Grant admin consent (the button at the top)

5. Configure Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Add this configuration (replace /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather with your actual path):

Basic configuration:

{
  "mcpServers": {
    "onenote": {
      "command": "uv",
      "args": [
        "--directory", "/FULL/PATH/TO/onenote-mcp-server",
        "run", "python", "onenote_mcp_server.py"
      ],
      "env": {
        "AZURE_CLIENT_ID": "your-azure-client-id-here"
      }
    }
  }
}

With explicit token caching control:

{
  "mcpServers": {
    "onenote": {
      "command": "uv",
      "args": [
        "--directory", "/FULL/PATH/TO/onenote-mcp-server",
        "run", "python", "onenote_mcp_server.py"
      ],
      "env": {
        "AZURE_CLIENT_ID": "your-azure-client-id-here",
        "ONENOTE_CACHE_TOKENS": "true"
      }
    }
  }
}

Replace /FULL/PATH/TO/onenote-mcp-server with the actual path to this project.

6. Restart Claude Desktop

Completely quit and restart Claude Desktop. You should see OneNote tools in the 🔨 menu.

🔐 First Time Authentication

1. In Claude Desktop, say: "Start OneNote authentication"
2. Claude will give you a URL and code
3. Visit the URL in your browser, enter the code, and sign in
4. Browser compatibility:
   • ✅ Firefox (tested with 139.0.4) - works perfectly
   • ❌ Safari - may have issues with Microsoft OAuth redirect
   • ✅ Chrome/Edge - should work (Microsoft's browsers)
5. Come back to Claude and say: "Complete OneNote authentication"
6. You're ready to go!

Token Persistence

By default, authentication tokens are cached securely on your local machine so you only need to authenticate once every few weeks/months.

To disable token caching (for security-sensitive environments):

{
  "mcpServers": {
    "onenote": {
      "command": "uv",
      "args": [
        "--directory", "/FULL/PATH/TO/onenote-mcp-server",
        "run", "python", "onenote_mcp_server.py"
      ],
      "env": {
        "AZURE_CLIENT_ID": "YOUR_CLIENT_ID_HERE",
        "ONENOTE_CACHE_TOKENS": "false"
      }
    }
  }
}

Token caching options:

• ONENOTE_CACHE_TOKENS=true (default) - Tokens persist across sessions
• ONENOTE_CACHE_TOKENS=false - Authenticate every session (more secure)

📖 Usage Examples

Once authenticated, try these commands in Claude Desktop:

List my OneNote notebooks
Show me sections in my Work notebook  
What pages are in my Ideas section?
Read the content of my "Project Plan" page

🛠 Troubleshooting

"No tools available" in Claude Desktop

• Make sure you restarted Claude Desktop after config changes
• Check that the path in your config is correct (use full absolute path)
• Verify uv is installed: uv --version

Authentication issues

• Safari OAuth problems: Safari may not handle Microsoft's OAuth redirect properly - use Firefox or Chrome instead
• "nativeclient" prompts: Normal Microsoft OAuth behavior, but if it blocks authentication, try a different browser
• Authentication expired: Use "Check OneNote authentication status" to see token expiry
• Clear cached tokens: Use "Clear OneNote token cache" if you need to reset authentication
• Recommended browsers: Firefox (confirmed working), Chrome, or Edge for best compatibility

"Command not found" errors

• Make sure uv is in your PATH
• Alternative: replace "uv" with "python" in the config and use the full path to your Python interpreter

Permission denied errors

• Check the file permissions in your project directory
• Make sure Claude Desktop can read the files

🏗 Development

Project Structure

onenote-mcp-server/
├── onenote_mcp_server.py      # Main server implementation
├── pyproject.toml             # Dependencies and metadata  
├── README.md                  # This file
├── LICENSE                    # MIT License
└── .gitignore                 # Git ignore rules

Key Features

• Two-step authentication: Handles device code flow properly
• Complete Graph API integration: All OneNote operations supported
• Robust error handling: Detailed logging and graceful failures
• FastMCP framework: Clean, maintainable code structure
• Environment variable configuration: Secure credential handling

Adding New Features

The server is built with FastMCP, making it easy to add new tools:

@mcp.tool()
async def your_new_tool(param: str) -> str:
    """Description of what your tool does."""
    # Your implementation here
    return result

🤝 Contributing

Contributions welcome! Please:

1. Fork the repo
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built with FastMCP framework
• Uses Microsoft Graph API for OneNote access
• Inspired by the amazing potential of AI + personal knowledge bases

⚠️ Important Notes

• This server only reads/writes data you already have access to
• Your Azure app credentials stay on your machine
• All authentication happens directly between you and Microsoft
• No data is sent to third parties

Built with ❤️ for the Claude + OneNote community

Turn your OneNote into an AI-accessible knowledge base!