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 MatimoInstance

matimo = await MatimoInstance.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 risk: high and 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. ms_send_teams_message, ms_create_document, and ms_create_calendar_event are risk: medium (external writes, narrower blast radius). The remaining read-only tools are risk: low.

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://matimo.dev/docs