npm package: @piyapat/office365-mcp-server
Description: MCP server for Office 365 email - draft and send with attachments via Microsoft Graph API
Latest version: 1.1.1

# @piyapat/office365-mcp-server

MCP server for Microsoft Office 365 email — create drafts and send email (with file attachments) via Microsoft Graph API.
**Email deletion is intentionally blocked.**

> **Note:** This package was previously published as `office365-mcp-server` and has been renamed to `@piyapat/office365-mcp-server`.

---

## Tools

| Tool | Description |
|---|---|
| `draft_email` | Create a draft email (saved, not sent) |
| `send_email` | Send an email immediately |
| `send_draft` | Send an existing draft by message ID |
| `list_drafts` | List drafts in the Drafts folder |
| `delete_email` | **BLOCKED** — always returns an error |

---

## Prerequisites

1. An **Azure AD App Registration** with:
   - Application permission: `Mail.Send`, `Mail.ReadWrite`
   - Admin consent granted for the tenant

2. **Node.js 18+**

---

## Azure AD App Registration

1. Go to [Azure Portal](https://portal.azure.com) → Azure Active Directory → App registrations → New registration
2. Note the **Application (client) ID** and **Directory (tenant) ID**
3. Certificates & secrets → New client secret → copy the value
4. API permissions → Add `Microsoft Graph` application permissions:
   - `Mail.Send`
   - `Mail.ReadWrite`
5. Grant admin consent

---

## Usage with npx (recommended)

### 1. Build locally (or publish to npm)

```bash
npm install
npm run build
```

### 2. Set environment variables

```bash
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"
```

### 3. Run with npx

```bash
npx @piyapat/office365-mcp-server
```

Or run directly:

```bash
node dist/index.js
```

---

## Claude Desktop / Claude Code configuration

Add to your `claude_desktop_config.json` or `.claude/mcp.json`:

```json
{
  "mcpServers": {
    "office365": {
      "command": "npx",
      "args": ["@piyapat/office365-mcp-server"],
      "env": {
        "AZURE_TENANT_ID": "your-tenant-id",
        "AZURE_CLIENT_ID": "your-client-id",
        "AZURE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

Or if running from a local build:

```json
{
  "mcpServers": {
    "office365": {
      "command": "node",
      "args": ["C:/Works/LLM/office365-mcp-server/dist/index.js"],
      "env": {
        "AZURE_TENANT_ID": "your-tenant-id",
        "AZURE_CLIENT_ID": "your-client-id",
        "AZURE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

---

## Tool reference

### `draft_email`
| Parameter | Type | Required | Description |
|---|---|---|---|
| `userEmail` | string | yes | Sender's O365 mailbox |
| `subject` | string | yes | Subject line |
| `body` | string | yes | Body content |
| `toRecipients` | `[{address, name?}]` | yes | To recipients |
| `ccRecipients` | `[{address, name?}]` | no | CC recipients |
| `bccRecipients` | `[{address, name?}]` | no | BCC recipients |
| `isHtml` | boolean | no | Body is HTML (default false) |
| `attachments` | `[{name, contentType, contentBytes}]` | no | File attachments (max ~3MB each, base64-encoded) |

### `send_email`
Same as `draft_email` plus:

| Parameter | Type | Required | Description |
|---|---|---|---|
| `saveToSentItems` | boolean | no | Save to Sent Items (default true) |

### `send_draft`
| Parameter | Type | Required | Description |
|---|---|---|---|
| `userEmail` | string | yes | Mailbox address |
| `messageId` | string | yes | Draft message ID |

### `list_drafts`
| Parameter | Type | Required | Description |
|---|---|---|---|
| `userEmail` | string | yes | Mailbox address |
| `top` | number | no | Max results 1–50 (default 10) |

### `delete_email` — BLOCKED
Always returns `OPERATION_BLOCKED` error. Cannot be enabled.

---

## Attachments

`draft_email` and `send_email` accept an optional `attachments` array. Each item must be:

```json
{
  "name": "report.pdf",
  "contentType": "application/pdf",
  "contentBytes": "<base64-encoded file content>"
}
```

**Limit:** ~3MB per file (Microsoft Graph inline attachment limit). For larger files, an upload session is required (not currently supported).

Common MIME types:

| File type | `contentType` |
|---|---|
| PDF | `application/pdf` |
| Word | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| Excel | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
| PNG | `image/png` |
| JPEG | `image/jpeg` |
| Plain text | `text/plain` |