The-Focus-AI Microsoft Outlook Email Skill
Access Outlook and Hotmail emails via the Microsoft Graph API. Supports reading messages, listing inbox contents, and downloading emails as .eml files.
Prerequisites
Before using email commands, ensure authentication is configured:
- Setup credentials (one-time):
pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts setup- Note: For personal accounts, ensure the app is registered as Multitenant + Personal Accounts in the Azure Portal. See the README for detailed steps.
- Authenticate (per-project):
pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts auth- Tip: Use
auth --browser Safarion macOS if your default browser is causing issues.
- Tip: Use
Available Commands
All commands output JSON for easy parsing.
Authentication & Setup
| Command | Description |
|---|---|
setup |
Configure Microsoft API credentials (interactive) |
auth |
Run OAuth flow - opens browser for login |
auth --global |
Store token globally instead of per-project |
check |
Verify authentication status |
User Information
| Command | Description |
|---|---|
me |
Get authenticated user profile |
Email Operations
| Command | Description |
|---|---|
messages |
List recent messages (default: 10) |
messages --limit N |
List N recent messages |
download <id> |
Download specific message as .eml file |
download-all |
Download recent messages to ./downloads |
download-all --limit N |
Download N recent messages |
Usage Pattern
Execute commands via:
pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts <command> [options]
Example Workflows
Check inbox:
pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts messages --limit 5
Download specific email:
pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts download <message-id>
Get user profile:
pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts me
Output Format
All commands return JSON:
messages response:
[
{
"id": "AAMk...",
"subject": "Meeting Tomorrow",
"receivedDateTime": "2024-01-15T10:30:00Z",
"from": {"emailAddress": {"name": "John", "address": "john@example.com"}},
"isRead": false,
"hasAttachments": true
}
]
me response:
{
"id": "user-id",
"displayName": "User Name",
"mail": "user@outlook.com",
"userPrincipalName": "user@outlook.com"
}
Token Storage
- Project tokens:
.claude/microsoft-skill.local.json(default) - Global tokens:
~/.config/microsoft-skill/tokens.json(with--global)
Project tokens allow different Microsoft accounts per project.
Authentication Flow
The skill uses OAuth 2.0 with PKCE:
- Run
authcommand - Browser opens to Microsoft login
- Grant permissions (Mail.Read, User.Read)
- Callback received on
localhost:3000 - Token stored for future use
Tokens auto-refresh when expired.
Troubleshooting
"Token not found" error:
Run authentication: pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts auth
"No credentials found" error:
Run setup: pnpm --prefix "${CLAUDE_PLUGIN_ROOT}" tsx scripts/microsoft.ts setup
Token expired:
The skill auto-refreshes tokens. If issues persist, re-run auth.
Additional Resources
Reference Files
references/setup-guide.md- Detailed Microsoft Entra app registration guidereferences/api-reference.md- Microsoft Graph API endpoints and types
Scripts
The main CLI script is at scripts/microsoft.ts with supporting libraries in scripts/lib/.