Back to Details

msgraph

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Microsoft Graph Agent Skill

Microsoft Graph Agent Skill

You can query and manage Microsoft 365 data through the Microsoft Graph API using the 
msgraph-skill
binary.
你可以通过
msgraph-skill
二进制工具使用Microsoft Graph API查询和管理Microsoft 365数据。

Quick Start

快速开始

  1. Check auth status before making any Graph call:
    msgraph-skill auth status
  2. Sign in if not authenticated:
    msgraph-skill auth signin
  3. Make Graph API calls:
    msgraph-skill graph-call GET /me
  1. 在发起任何Graph调用前先检查认证状态:
    msgraph-skill auth status
  2. 如果未认证请登录:
    msgraph-skill auth signin
  3. 发起Graph API调用:
    msgraph-skill graph-call GET /me

Authentication

身份验证

The tool handles authentication automatically using Microsoft's identity platform (MSAL).
  • Interactive browser auth is the default — a browser window opens for sign-in
  • Device code flow is used automatically when no browser is detected (SSH sessions, containers) or can be forced with 
    --device-code
  • Incremental consent is handled automatically — if a 403 Forbidden is returned, the tool re-authenticates with the required scopes and retries
  • Session-scoped cache — tokens are cached in a temp file for the session only; no persistent credential storage
该工具使用微软身份平台（MSAL）自动处理身份验证。
  • 默认采用交互式浏览器认证——会打开浏览器窗口供登录
  • 当未检测到浏览器时（SSH会话、容器环境）会自动使用设备码流，也可以通过
    --device-code
    参数强制启用
  • 自动处理增量同意——如果返回403 Forbidden错误，工具会使用所需权限范围重新认证并重试
  • 会话级缓存——令牌仅临时缓存到会话的临时文件中，不会持久化存储凭证

Auth Commands

认证命令

CommandDescription
msgraph-skill auth signin
Sign in to Microsoft 365
msgraph-skill auth signin --device-code
Sign in using device code flow
msgraph-skill auth signin --scopes "Mail.Read,Calendars.Read"
Sign in requesting specific scopes
msgraph-skill auth signout
Clear the current session
msgraph-skill auth status
Check if signed in and show account info
msgraph-skill auth switch-tenant <tenant-id>
Switch to a different M365 tenant
命令描述
msgraph-skill auth signin
登录Microsoft 365
msgraph-skill auth signin --device-code
使用设备码流登录
msgraph-skill auth signin --scopes "Mail.Read,Calendars.Read"
登录时请求指定权限范围
msgraph-skill auth signout
清除当前会话
msgraph-skill auth status
检查登录状态并展示账户信息
msgraph-skill auth switch-tenant <tenant-id>
切换到其他M365租户

Making Graph API Calls

发起Graph API调用

Use 
msgraph-skill graph-call <METHOD> <URL>
to execute REST calls against the Graph API.
使用
msgraph-skill graph-call <METHOD> <URL>
向Graph API发起REST调用。

Read Operations (default)

读操作（默认）

bash
undefined
bash
undefined

Get current user profile

获取当前用户资料

msgraph-skill graph-call GET /me
msgraph-skill graph-call GET /me

List users with selected fields

列出用户的指定字段

msgraph-skill graph-call GET /users --select "displayName,mail,userPrincipalName" --top 10
msgraph-skill graph-call GET /users --select "displayName,mail,userPrincipalName" --top 10

Get user's mail with filtering

筛选获取用户邮件

msgraph-skill graph-call GET /me/messages --filter "isRead eq false" --top 5 --select "subject,from,receivedDateTime"
msgraph-skill graph-call GET /me/messages --filter "isRead eq false" --top 5 --select "subject,from,receivedDateTime"

List groups

列出组

msgraph-skill graph-call GET /groups --select "displayName,description" --top 25
msgraph-skill graph-call GET /groups --select "displayName,description" --top 25

Get team channels

获取团队频道

msgraph-skill graph-call GET /teams/{team-id}/channels
msgraph-skill graph-call GET /teams/{team-id}/channels

Search users

搜索用户

msgraph-skill graph-call GET /users --filter "startsWith(displayName,'John')"
undefined
msgraph-skill graph-call GET /users --filter "startsWith(displayName,'John')"
undefined

Write Operations (requires --allow-writes)

写操作（需要--allow-writes参数）

IMPORTANT: Before making any write operation (POST, PUT, PATCH), you MUST ask the user for confirmation. Write operations require the 
--allow-writes
flag.
bash
undefined
重要提示: 在发起任何写操作（POST、PUT、PATCH）之前，你必须向用户请求确认。写操作需要携带
--allow-writes
标识。
bash
undefined

Send a message (ask user first!)

发送消息（请先询问用户！）

msgraph-skill graph-call POST /me/sendMail --body '{"message":{"subject":"Hello","body":{"content":"Hi there"},"toRecipients":[{"emailAddress":{"address":"user@example.com"}}]}}' --allow-writes
msgraph-skill graph-call POST /me/sendMail --body '{"message":{"subject":"Hello","body":{"content":"Hi there"},"toRecipients":[{"emailAddress":{"address":"user@example.com"}}]}}' --allow-writes

Update user properties (ask user first!)

更新用户属性（请先询问用户！）

msgraph-skill graph-call PATCH /me --body '{"jobTitle":"Engineer"}' --allow-writes

**DELETE operations are always blocked** for safety regardless of flags.
msgraph-skill graph-call PATCH /me --body '{"jobTitle":"Engineer"}' --allow-writes

**出于安全考虑，DELETE操作始终被禁止**，无论是否携带对应标识。

Query Parameters

查询参数

FlagDescriptionExample
--select
OData $select
--select "displayName,mail"
--filter
OData $filter
--filter "isRead eq false"
--top
OData $top (limit results)
--top 10
--expand
OData $expand
--expand "members"
--orderby
OData $orderby
--orderby "displayName"
--api-version
API version (v1.0 or beta)
--api-version v1.0
--scopes
Request additional scopes
--scopes "Mail.Read"
--headers
Custom HTTP headers
--headers "ConsistencyLevel:eventual"
--output
Output format (json or raw)
--output raw
标识描述示例
--select
OData $select
--select "displayName,mail"
--filter
OData $filter
--filter "isRead eq false"
--top
OData $top（限制结果数量）
--top 10
--expand
OData $expand
--expand "members"
--orderby
OData $orderby
--orderby "displayName"
--api-version
API版本（v1.0或beta）
--api-version v1.0
--scopes
请求额外权限范围
--scopes "Mail.Read"
--headers
自定义HTTP头
--headers "ConsistencyLevel:eventual"
--output
输出格式（json或raw）
--output raw

Finding the Right Endpoint

查找合适的端点

Strategy

查找策略

  1. First: Try constructing the Graph API call from your training knowledge. The Microsoft Graph API follows consistent patterns:
    • /me
      — current user
    • /users
      — all users
    • /users/{id}
      — specific user
    • /me/messages
      — current user's mail
    • /groups
      — all groups
    • /teams/{id}/channels
      — team channels
  2. If unsure: Use the OpenAPI search command to find endpoints:
    msgraph-skill openapi-search --query "send mail"
msgraph-skill openapi-search --resource users --method GET
msgraph-skill openapi-search --query "calendar events" --method POST
  3. Check the reference for detailed API documentation: See references/REFERENCE.md for common Graph API patterns and endpoint details.
  1. 首先: 根据你的训练知识尝试构造Graph API调用。Microsoft Graph API遵循统一的模式:
    • /me
      — 当前用户
    • /users
      — 所有用户
    • /users/{id}
      — 指定用户
    • /me/messages
      — 当前用户的邮件
    • /groups
      — 所有组
    • /teams/{id}/channels
      — 团队频道
  2. 如果不确定: 使用OpenAPI搜索命令查找端点:
    msgraph-skill openapi-search --query "send mail"
msgraph-skill openapi-search --resource users --method GET
msgraph-skill openapi-search --query "calendar events" --method POST
  3. 查阅参考文档获取详细API说明: 查看 references/REFERENCE.md 了解常见Graph API模式和端点详情。

OpenAPI Search Command

OpenAPI搜索命令

bash
undefined
bash
undefined

Search by keyword

按关键词搜索

msgraph-skill openapi-search --query "list users"
msgraph-skill openapi-search --query "list users"

Search by resource and method

按资源和请求方法搜索

msgraph-skill openapi-search --resource messages --method GET
msgraph-skill openapi-search --resource messages --method GET

Combined search

组合搜索

msgraph-skill openapi-search --query "create" --resource groups --method POST
undefined
msgraph-skill openapi-search --query "create" --resource groups --method POST
undefined

Important Rules

重要规则

  1. Always check auth status before the first Graph call in a session
  2. GET requests are the default — no special flags needed
  3. Write operations require 
    --allow-writes
     — always confirm with the user first
  4. DELETE is always blocked — inform the user this is not supported
  5. The default API version is beta — use 
    --api-version v1.0
    for production-stable endpoints
  6. 403 errors trigger automatic re-auth — the tool will request additional scopes and retry
  7. All output is JSON — parse the 
    statusCode
    and 
    body
    fields from the response
  1. 会话中第一次调用Graph前始终检查认证状态
  2. 默认支持GET请求——无需特殊标识
  3. 写操作需要
    --allow-writes
    参数    ——使用前必须获得用户确认
  4. DELETE操作始终被禁止——告知用户该操作不支持
  5. 默认API版本为beta——生产环境稳定端点请使用
    --api-version v1.0
  6. 403错误会触发自动重认证——工具会请求额外权限并重试
  7. 所有输出为JSON格式——请从响应中解析
    statusCode
    和
    body
    字段

Error Handling

错误处理

  • 401 Unauthorized: Token expired. Run 
    msgraph-skill auth signin
    again.
  • 403 Forbidden: Insufficient permissions. The tool automatically attempts incremental consent. If it still fails, the user may need admin consent for those permissions.
  • 404 Not Found: The resource doesn't exist or the URL is incorrect. Verify the endpoint path.
  • 429 Too Many Requests: Rate limited. Wait and retry.
  • 401 Unauthorized: 令牌过期，请重新运行
    msgraph-skill auth signin
  • 403 Forbidden: 权限不足，工具会自动尝试增量同意。如果仍然失败，用户可能需要管理员同意对应权限
  • 404 Not Found: 资源不存在或URL错误，请校验端点路径
  • 429 Too Many Requests: 请求频率超限，请等待后重试

Environment Variables

环境变量

VariableDescriptionDefault
MSGRAPH_CLIENT_ID
Custom Azure AD app registration client IDMicrosoft Graph CLI Tools app
MSGRAPH_TENANT_ID
Target tenant ID
common
(multi-tenant)
MSGRAPH_API_VERSION
Default API version
beta
MSGRAPH_INDEX_PATH
Path to OpenAPI index JSONAuto-detected
变量描述默认值
MSGRAPH_CLIENT_ID
自定义Azure AD应用注册客户端IDMicrosoft Graph CLI Tools应用
MSGRAPH_TENANT_ID
目标租户ID
common
（多租户）
MSGRAPH_API_VERSION
默认API版本
beta
MSGRAPH_INDEX_PATH
OpenAPI索引JSON路径自动检测