OutNote

Headless Microsoft 365 reader - mail, calendar, Teams, OneDrive, SharePoint and OneNote over Graph, without an app registration.

About The Project

Every "read my mailbox over Graph" tutorial makes you register an Azure app and get admin consent - which a locked-down tenant (a school, a company) simply refuses. OutNote sidesteps that entirely.

It signs in with entrance using the pre-consented OfficeHome first-party client, which hands back a FOCI family refresh token. A tiny broker then trades that token for whichever first-party client's Graph token a given call needs - all without another sign-in. Each of those clients is already consented in the tenant, so there is nothing to register and nobody to ask.

The result: one headless login (password + TOTP MFA, no browser), then clean Graph reads across your whole Microsoft 365 account. Built to be the base layer for an MCP server.

Features

• 🔓 No app registration, no admin consent - rides pre-consented Microsoft first-party clients
• 🤖 Fully headless - password + TOTP MFA over pure HTTP, no browser (via entrance)
• 🧩 One login, every service - a FOCI family token is brokered into the right client per call
• 📬 Broad coverage - mail, calendar, Teams chats & channels, channel files, OneDrive, SharePoint, OneNote
• 🍪 Silent reuse - a persisted session jar means password-free reruns
• 📦 Tiny - stdlib urllib Graph client, one dependency (ms-entrance)

Installation

pip install outnote
# or
uv add outnote

Requires Python 3.10+; ms-entrance is pulled in automatically.

Quickstart

from outnote import authenticate

note = authenticate(
    "you@school.ch",
    "your-password",
    totp_secret="JBSWY3DPEHPK3PXP",  # Base32 TOTP, if the account has MFA
)

# mail & calendar
note.emails(top=5)
note.events(top=5)

# Teams chats
for chat in note.chats():
    note.chat_messages(chat["id"])

# Teams channels + files
for team in note.teams():
    for ch in note.channels(team["id"]):
        note.channel_messages(team["id"], ch["id"])
        note.channel_files(team["id"], ch["id"])  # files posted in the channel

# OneDrive & SharePoint
note.files()  # OneDrive items
note.download_url(item_id)  # direct, pre-authed download link
note.sites()  # SharePoint sites

# search across the account
note.search_emails("invoice")
note.search_files("budget.xlsx")
note.search_messages("standup")  # Teams chat & channel messages
note.search_people("Fischer")
note.search("project kickoff", entity="event")  # any entity type

# OneNote - list and read page content as HTML
for nb in note.notebooks():
    for sec in note.sections(nb["id"]):
        for page in note.pages(sec["id"]):
            html = note.page_content(page["id"])

note.get("me/drive/root/children")  # any Graph endpoint, raw

The first call saves .ms_session.json; every call after that skips the password and MFA.

Already have a Graph token (MSAL, a browser session, ...)? Skip auth entirely. A single static token only carries its own scopes, so OneNote/SharePoint calls may 403 if it lacks them:

from outnote import OutNote

OutNote(access_token).emails()

What it does

Verified end-to-end against a live locked-down EDU tenant:

How It Works

authenticate runs a PKCE authorization-code sign-in for the OfficeHome client through entrance (which drives Microsoft's sign-in - including TOTP MFA - over pure HTTP and intercepts the code at the native-client redirect), then redeems it for a FOCI family refresh token. The OutNote client holds a broker that, per call, refreshes that token into the first-party client whose pre-consented scopes cover the request, caching each token until it expires:

Which first-party clients are FOCI-family and pre-consented is tenant-dependent; the three above work on a standard Microsoft 365 / EDU tenant.

Caveats

• Works against managed Entra tenants (login.microsoftonline.com) with these first-party clients pre-consented - the common case for Microsoft 365 / EDU.
• Push / SMS MFA can't be done headless - only TOTP (authenticator app). Enroll one and pass its Base32 secret.
• Microsoft tweaks its login pages and client registrations; if a flow breaks, a user-agent, field name or client ID is usually the culprit.

Disclaimer

OutNote is published for educational and research purposes only - to document how Microsoft 365's first-party OAuth2 clients and the Graph API behave for a browserless client.

Use it only against accounts you own, or with the explicit authorization of the account or tenant owner. You alone are responsible for your use of it and for complying with Microsoft's terms, your identity provider's terms, your institution's acceptable-use policy, and applicable law. The software is provided "as is", without warranty of any kind, and the author accepts no liability for misuse. Not affiliated with or endorsed by Microsoft.

License

MIT (c) PianoNic