matimo-microsoft

Microsoft Graph tools for Matimo - search, OneDrive/SharePoint files, Outlook mail, Microsoft Teams, calendar, and SharePoint publishing.

Installation

pip install matimo matimo-microsoft

Available Tools (9 Total)

Quick Start

from matimo import Matimo

matimo = await Matimo.init(auto_discover=True)

# Search across SharePoint and OneDrive
search = await matimo.execute("ms_search_knowledge", {"query": "Q3 budget filetype:xlsx", "top": 5})

# List messages in the signed-in user's mailbox
inbox = await matimo.execute("ms_get_email", {"top": 5, "filter": "isRead eq false"})

# Send an email (requires_approval: true - routed through HITL)
await matimo.execute(
    "ms_send_email",
    {"to": ["alice@contoso.com"], "subject": "Weekly status update", "body": "Here is the summary..."},
)

Authentication

Microsoft Graph tools use delegated OAuth2 access tokens. Matimo never performs the OAuth code exchange itself - connect Microsoft through your Matimo deployment (Nova), then provide the resulting token at execution time:

export MICROSOFT_GRAPH_ACCESS_TOKEN="eyJ0eXAiOiJKV1Qi..."

or pass it through per-call credentials:

await matimo.execute(
    "ms_get_email",
    {"top": 5},
    credentials={"MICROSOFT_GRAPH_ACCESS_TOKEN": token},
)

Risk & Approval

ms_send_email and ms_publish_to_sharepoint are marked requires_approval: true - Matimo routes them through the human-in-the-loop approval flow before they execute, since they send mail and publish content visible to others on the user's behalf. The other 7 tools have no requires_approval flag and execute immediately.

None of the 9 tools declare an explicit risk: field in their YAML. If you enable HITL quarantine (enableHITL=True with a quarantineRiskLevels policy config), be aware that every tool in this package uses execution.type: function, and Matimo's automatic risk classifier assigns type: function tools risk: critical by default regardless of what they actually do - so all 9 tools, including the read-only ones, will classify as critical if critical is in your quarantineRiskLevels.

Documentation

• Microsoft Graph API overview
• Graph Explorer
• Python Examples - Direct SDK
• Python Examples - LangChain agent
• Python Examples - CrewAI crew

Links

• PyPI: https://pypi.org/project/matimo-microsoft/
• GitHub: https://github.com/tallclub/matimo
• Microsoft Graph API Docs: https://learn.microsoft.com/en-us/graph/overview
• Matimo documentation: https://docs.matimo.dev/