graph-cli 2.0.1

graph-cli

A .NET global tool for interacting with Microsoft Graph — manage emails, calendar events, Teams chats, To Do tasks, presence, user directory, and OneDrive/SharePoint files from the command line or via MCP for AI assistants like Claude. Output is JSON by default (--format table for human-readable output).

Installation

Requires .NET 10 SDK or later.

# Install from NuGet
dotnet tool install -g graph-cli

Or install from source:

git clone https://github.com/afroze9/graph-cli.git
cd graph-cli
dotnet pack -o ./nupkg
dotnet tool install -g graph-cli --add-source ./nupkg

Setup (First-Time Users)

1. Register an Azure AD App

1. Go to Azure Portal → App registrations and click New registration
2. Name it something like graph-cli, set Supported account types to "Single tenant", and set Redirect URI to http://localhost (type: Public client/native)
3. After creation, copy the Application (client) ID and Directory (tenant) ID from the Overview page
4. Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions and add:
   • User.Read, User.ReadBasic.All
   • Mail.ReadWrite, Mail.Send
   • Calendars.Read.Shared, Calendars.ReadWrite
   • Chat.Create, Chat.ReadWrite, ChatMessage.Read, ChatMessage.Send
   • Presence.Read.All
   • Tasks.ReadWrite
   • Files.Read.All, Sites.Read.All
5. Click Grant admin consent (or ask your tenant admin to do this)

2. Configure graph-cli

Create ~/.graph-cli/config.json:

{
  "tenantId": "<your-tenant-id>",
  "clientId": "<your-client-id>"
}

Or set environment variables GRAPH_CLI_TENANT_ID and GRAPH_CLI_CLIENT_ID instead.

3. Authenticate

graph-cli auth login    # Opens browser for interactive auth (only needed once)
graph-cli auth status   # Check if authenticated
graph-cli auth logout   # Clear cached tokens

Tokens are cached at ~/.graph-cli/token-cache.bin and auto-refresh silently — you won't need to log in again unless you explicitly log out.

Using as an MCP Server (Claude Desktop, Cursor, etc.)

graph-cli includes a built-in MCP (Model Context Protocol) server, so AI assistants like Claude can interact with your Microsoft 365 data directly.

1. Register an Azure AD App

Follow step 1 from Setup above if you haven't already.

2. Add to Claude Desktop

Edit your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "graph-cli": {
      "command": "graph-cli",
      "args": ["mcp"],
      "env": {
        "GRAPH_CLI_TENANT_ID": "<your-tenant-id>",
        "GRAPH_CLI_CLIENT_ID": "<your-client-id>",
        "GRAPH_CLI_SCOPES": "User.Read,User.ReadBasic.All,Mail.ReadWrite,Mail.Send,Calendars.Read.Shared,Calendars.ReadWrite,Chat.Create,Chat.ReadWrite,ChatMessage.Read,ChatMessage.Send,Presence.Read.All,Tasks.ReadWrite,Files.Read.All,Sites.Read.All"
      }
    }
  }
}

No config.json needed — the MCP config provides everything. On first tool call, a browser window will open for Microsoft login. After that, tokens are cached and refresh automatically.

3. Restart Claude Desktop

You should see graph-cli tools available. Ask Claude something like "What's my email address?" or "Show my calendar for today" to verify.

Troubleshooting

• "Authentication required" — Run graph-cli auth login in a terminal, then retry.
• "No configuration found" — Check that GRAPH_CLI_TENANT_ID and GRAPH_CLI_CLIENT_ID are set in your MCP config, or create ~/.graph-cli/config.json (see Setup).
• Tools not appearing — Run graph-cli auth status in a terminal to check that auth is working.

Quick Start

# Check your profile
graph-cli user me --format table

# See latest emails
graph-cli mail list --top 5 --format table

# Check today's calendar
graph-cli calendar events --format table

# Allow a contact before sending
graph-cli contacts allow jane@company.com --actions email,chat
graph-cli mail send --to jane@company.com --subject "Hello" --body "Hi Jane"

Commands

Command Availability

All commands are available via both the CLI and the MCP server unless noted otherwise.

Commands marked — in MCP are either interactive-only (auth login, auth logout) or involve file system operations (download-attachment, files download) that don't translate to the MCP context.

Mail

graph-cli mail list [--top <n>] [--folder <name>]
graph-cli mail get <message-id>
graph-cli mail search --query <text> [--top <n>]
graph-cli mail send --to <emails> --subject <text> --body <text> [--cc <emails>] [--content-type text|html]
graph-cli mail draft --to <emails> --subject <text> --body <text>
graph-cli mail send-draft <message-id>
graph-cli mail mark-read <message-id> [<id2> ...] [--unread]
graph-cli mail move <message-id> [<id2> ...] --folder <folder-id-or-name>
graph-cli mail delete <message-id> [<id2> ...]
graph-cli mail folders [--parent <folder-id-or-name>]
graph-cli mail attachments <message-id>
graph-cli mail download-attachment <message-id> <attachment-id> [--out <path>]

Calendar

graph-cli calendar list
graph-cli calendar events [--start <iso-date>] [--end <iso-date>] [--calendar-id <id>] [--top <n>]
graph-cli calendar get-event <event-id>
graph-cli calendar create-event --subject <text> --start <iso-datetime> --end <iso-datetime> \
    [--attendees <emails>] [--body <text>] [--content-type text|html] \
    [--categories <names>] [--location <text>] [--online-meeting] [--calendar-id <id>]
graph-cli calendar update-event <event-id> [--subject <text>] [--start <datetime>] [--end <datetime>] \
    [--body <text>] [--content-type text|html] [--categories <names>]
graph-cli calendar delete-event <event-id>
graph-cli calendar respond <event-id> --action accept|decline|tentative [--comment <text>]
graph-cli calendar find-times --attendees <emails> --duration <minutes> [--start <iso-datetime>] [--end <iso-datetime>]
graph-cli calendar schedule --users <emails> --start <iso-datetime> --end <iso-datetime>

Chat (Teams)

graph-cli chat list [--top <n>]
graph-cli chat search --query <text> [--top <n>] [--refresh]
graph-cli chat get <chat-id>
graph-cli chat create --members <emails> [--topic <text>] [--type oneOnOne|group]
graph-cli chat members <chat-id>
graph-cli chat messages <chat-id> [--top <n>]
graph-cli chat send <chat-id> --message <text> [--content-type text|html] [--mentions <id:email,...>]
graph-cli chat reply <chat-id> <message-id> --message <text> [--mentions <id:email,...>]

Presence

graph-cli presence me
graph-cli presence get <user-id>
graph-cli presence batch --user-ids <comma-separated-ids>

Tasks (Microsoft To Do)

graph-cli task lists
graph-cli task list <list-id> [--status notStarted|inProgress|completed]
graph-cli task create <list-id> --title <text> [--due <iso-date>] [--importance low|normal|high] [--body <text>]
graph-cli task update <list-id> <task-id> [--title <text>] [--status notStarted|inProgress|completed] [--due <date>] [--importance low|normal|high]
graph-cli task complete <list-id> <task-id>
graph-cli task delete <list-id> <task-id>

Files (OneDrive & SharePoint)

graph-cli files list [--folder <item-id>] [--drive-id <id>] [--site <site-id-or-hostname>] [--top <n>]
graph-cli files get <item-id-or-sharing-url> [--drive-id <id>] [--site <site>]
graph-cli files download <item-id-or-sharing-url> [--out <path>] [--drive-id <id>] [--site <site>]
graph-cli files search <query> [--drive-id <id>] [--site <site>] [--top <n>] [--refresh]
graph-cli files share <item-id-or-sharing-url> --recipients <emails> [--role read|write|owner] [--message <text>] [--drive-id <id>] [--site <site>]

User Directory

graph-cli user me
graph-cli user get <user-id-or-email>
graph-cli user search --query <text>
graph-cli user manager
graph-cli user reports

Contacts Allow-List

Outbound actions (mail send, chat send, file share, etc.) are gated by an allowed contacts list for safety.

graph-cli contacts allow <email-or-group> --actions email,chat,share [--name "Display Name"] [--type user|group]
graph-cli contacts list [--type user|group]
graph-cli contacts remove <email-or-group>

SharePoint Sites, Pages & Lists

graph-cli sites search <query> [--top <n>] [--refresh]
graph-cli pages list --site <site> [--top <n>] [--search <text>]
graph-cli pages get <page-id> --site <site> [--expand-content]
graph-cli lists list --site <site>
graph-cli lists items <list-id> --site <site> [--top <n>] [--fields <field1,field2>] [--filter <odata-filter>]

Architecture

graph-cli uses a layered architecture where core business logic lives in shared services, exposed via both the CLI and MCP interfaces:

Services/           ← Core logic (Graph SDK calls)
  ├── UserService.cs
  ├── MailService.cs
  ├── CalendarService.cs
  ├── ...
  │
Commands/           ← CLI layer (arg parsing, output formatting)
  ├── UserCommands.cs
  ├── MailCommands.cs
  ├── ...
  │
McpTools/           ← MCP layer (JSON serialization, tool registration)
  ├── UserTools.cs
  ├── MailTools.cs
  ├── ...

Global Options

Environment Variables

License

MIT