ms-graph

A Python client for the Microsoft Graph API, covering OneDrive, SharePoint, Outlook Mail, OneNote, Contacts, Excel Workbooks, Users, Groups, and Search.

---

Installation

pip install ms-graph

Or with Poetry:

poetry add ms-graph

---

Prerequisites

Register an application in the Azure Portal to obtain:

• Client ID
• Client Secret
• Redirect URI

Grant the required Microsoft Graph API permissions for the services you intend to use.

---

Quick Start

from ms_graph import MicrosoftGraphClient

client = MicrosoftGraphClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    redirect_uri="YOUR_REDIRECT_URI",
    scope=["Files.Read", "Files.ReadWrite", "Mail.Read"],
    account_type="consumers",  # or "organizations" / "common"
)

# Opens a browser prompt on first run to complete OAuth2 flow.
# Subsequent runs use a saved token / refresh token automatically.
client.login()

Credentials are persisted to a local JSON file (or Azure Key Vault — see below). On subsequent runs, tokens are refreshed silently.

---

Services

OneDrive — Drives

drives = client.drives()

# Root drive
root = drives.get_root_drive()

# Children of root
children = drives.get_root_drive_children()

# Recent files
recent = drives.get_recent_files()

# Shared with me
shared = drives.get_shared_files()

OneDrive — Drive Items

items = client.drive_item()

# By item ID
item = items.get_drive_item(drive_id="DRIVE_ID", item_id="ITEM_ID")

# By path
item = items.get_drive_item_by_path(drive_id="DRIVE_ID", item_path="Documents/report.xlsx")

# Group drive item
item = items.get_group_drive_item(group_id="GROUP_ID", item_id="ITEM_ID")

Outlook Mail

mail = client.mail()

# List messages for signed-in user
messages = mail.list_my_messages()

# List messages for a specific user
messages = mail.list_user_messages(user_id="user@example.com")

# Get a specific message
msg = mail.get_my_messages(message_id="MESSAGE_ID")

# Create a draft
draft = mail.create_my_message(message={
    "subject": "Hello",
    "body": {"contentType": "Text", "content": "Hi there"},
    "toRecipients": [{"emailAddress": {"address": "recipient@example.com"}}]
})

OneNote

notes = client.notes()

# My notebooks
notebooks = notes.list_my_notebooks()

# Notebooks for a specific user
notebooks = notes.list_user_notebooks(user_id="user@example.com")

# Notebooks for a group
notebooks = notes.list_group_notebooks(group_id="GROUP_ID")

Personal Contacts

contacts = client.personal_contacts()

# All contacts
all_contacts = contacts.list_my_contacts()

# Contact folders
folders = contacts.list_my_contacts_folder()

# Folder by ID
folder = contacts.list_contacts_folder_by_id(user_id="USER_ID", folder_id="FOLDER_ID")

Users

users = client.users()

all_users = users.list_users()

Groups

groups = client.groups()

all_groups = groups.list_groups()

Search

search = client.search()

results = search.query(search_request={
    "requests": [{
        "entityTypes": ["driveItem"],
        "query": {"queryString": "quarterly report"}
    }]
})

Excel Workbooks

workbooks = client.workbooks()

# Create a session (enables batching edits)
session = workbooks.create_session(item_path="Documents/report.xlsx")
session_id = session["id"]

# Refresh the session
workbooks.refresh_session(session_id=session_id, item_path="Documents/report.xlsx")

# Close the session
workbooks.close_session(session_id=session_id, item_path="Documents/report.xlsx")

Excel Worksheets

from ms_graph.workbooks_and_charts import Worksheet

worksheet = Worksheet(session=client.graph_session)

# Add a new sheet
worksheet.add_worksheet(item_path="Documents/report.xlsx", name="Summary")

Excel Range

range_svc = client.range()

# Get a range by address
data = range_svc.get_range(
    item_path="Documents/report.xlsx",
    worksheet_name_or_id="Sheet1",
    address="A1:C5"
)

Excel Tables

table_svc = client.table()

---

Credential Storage Options

Option 1 — JSON file (default)

Pass a file path as credentials. The token is saved/loaded automatically:

client = MicrosoftGraphClient(
    client_id="...",
    client_secret="...",
    redirect_uri="...",
    scope=[...],
    credentials="./ms_graph_state.json",
)

Option 2 — Azure Key Vault

Pass an Az client from azkees and set the env var key_msgraph_credentials_state to the Key Vault secret name where the token JSON will be stored:

import os
from azkees import Az
from ms_graph import MicrosoftGraphClient

os.environ["key_msgraph_credentials_state"] = "msgraphstate"

az_client = Az(config_section="production", keys_config_path="/app/config/api_keys.ini")

client = MicrosoftGraphClient(
    client_id="...",
    client_secret="...",
    redirect_uri="...",
    scope=[...],
    az_client=az_client,
)

---

Enums

from ms_graph.workbooks_and_charts.enums import (
    CalculationTypes,
    WorksheetVisibility,
    RangeShift,
    Underline,
)

CalculationTypes.RECALCULATE.value   # "Recalculate"
WorksheetVisibility.HIDDEN.value     # "Hidden"
RangeShift.DOWN.value                # "Down"

---

Changelog

See CHANGELOG.md for version history.

License

MIT

Author

Bharani Nitturi