README
¶
msgraph
An Agent Skill for the Microsoft Graph API. Enables AI agents to authenticate to Microsoft 365 tenants and make Graph API calls.
Features
- MSAL Authentication - Interactive browser flow with device code fallback
- Graph API Calls - Execute REST API calls against Microsoft Graph (beta and v1.0)
- Read-Only by Default - GET operations allowed; write operations require explicit confirmation
- Incremental Consent - Automatically requests additional permissions when needed
- OpenAPI Lookup - Pre-processed Graph API index for endpoint discovery
- Cross-Platform - Cross-platform CLI for macOS, Linux, and Windows (amd64/arm64)
- Zero Runtime Dependencies - No runtime installation needed
Quick Start
Install the Skill
Using skills.sh (recommended):
npx skills add merill/msgraph
Or download from GitHub Releases:
Download msgraph.zip from the latest release, then extract it into your agent's skills directory:
# Download and extract
curl -fsSL -o msgraph.zip https://github.com/merill/msgraph/releases/latest/download/msgraph.zip
unzip msgraph.zip -d ~/.claude/skills/
First Run
The launcher script automatically downloads the correct binary for your platform on first run.
macOS/Linux:
bash ~/.claude/skills/msgraph/scripts/run.sh auth signin
Windows:
powershell ~/.claude/skills/msgraph/scripts/run.ps1 auth signin
Make API Calls
# Get current user profile
msgraph graph-call GET /me
# List messages
msgraph graph-call GET /me/messages --top 10
# Search the OpenAPI index
msgraph openapi-search --query "send mail"
Configuration
| Environment Variable | Description | Default |
|---|---|---|
MSGRAPH_CLIENT_ID |
Override the default app client ID | 14d82eec-204b-4c2f-b7e8-296a70dab67e |
MSGRAPH_TENANT_ID |
Target a specific tenant | common |
MSGRAPH_API_VERSION |
Default API version (beta or v1.0) |
beta |
Building from Source
Requires Go 1.22+ to build from source.
# Build for current platform
make build
# Build for all platforms
make build-all
# Run the OpenAPI indexer
make index
Project Structure
msgraph/
├── skills/msgraph/ # The installable Agent Skill
│ ├── SKILL.md # Agent Skills spec entry point
│ ├── scripts/ # Launcher scripts + binary cache
│ └── references/ # OpenAPI index + reference docs
├── cmd/ # CLI subcommands (Cobra)
├── internal/ # Internal packages
├── tools/ # Build-time tools (OpenAPI indexer)
├── docs/ # Documentation site (Astro + Starlight)
└── .github/ # CI/CD workflows
License
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd implements the CLI commands for msgraph.
|
Package cmd implements the CLI commands for msgraph. |
|
internal
|
|
|
auth
Package auth provides authentication for Microsoft Graph using MSAL.
|
Package auth provides authentication for Microsoft Graph using MSAL. |
|
config
Package config provides configuration management for the msgraph CLI.
|
Package config provides configuration management for the msgraph CLI. |
|
graph
Package graph provides an HTTP client for Microsoft Graph API calls with built-in safety enforcement and incremental consent support.
|
Package graph provides an HTTP client for Microsoft Graph API calls with built-in safety enforcement and incremental consent support. |
|
openapi
Package openapi provides search functionality over a pre-processed Microsoft Graph OpenAPI index.
|
Package openapi provides search functionality over a pre-processed Microsoft Graph OpenAPI index. |
|
samples
Package samples provides search functionality over community-contributed Microsoft Graph API query samples.
|
Package samples provides search functionality over community-contributed Microsoft Graph API query samples. |
|
tools
|
|
|
openapi-indexer
command
Command openapi-indexer downloads and processes the Microsoft Graph OpenAPI specification into a compact searchable JSON index.
|
Command openapi-indexer downloads and processes the Microsoft Graph OpenAPI specification into a compact searchable JSON index. |
Click to show internal directories.
Click to hide internal directories.