{"_id":"@mindstone/mcp-server-microsoft-mail","_rev":"5-628bc1f0b52bb6b09e49c320ce2443f7","name":"@mindstone/mcp-server-microsoft-mail","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@mindstone/mcp-server-microsoft-mail","version":"0.1.0","license":"FSL-1.1-MIT","_id":"@mindstone/mcp-server-microsoft-mail@0.1.0","maintainers":[{"name":"mindstone-engineering","email":"engineering@mindstone.com"}],"homepage":"https://github.com/mindstone/mcp-servers/tree/main/connectors/microsoft-mail","bugs":{"url":"https://github.com/mindstone/mcp-servers/issues"},"bin":{"mcp-server-microsoft-mail":"dist/index.js"},"dist":{"shasum":"bd7e583a4438fe163141a05349f7a54249f38f20","tarball":"https://registry.npmjs.org/@mindstone/mcp-server-microsoft-mail/-/mcp-server-microsoft-mail-0.1.0.tgz","fileCount":33,"integrity":"sha512-ZOelYSzhoGSEmxLCNSyoXiXAebPacX8S+DqgXNZdMB5KwqAz81l3B0DhNFThsUy08qUIRu0lDFNfQ2DYq0qbhw==","signatures":[{"sig":"MEUCIF+FflJT68ZCAyvPkwcyQcGko5Y81kIVIbbzU4UTeYruAiEAhNdywS4F+zzl3XOudlolcAIjPphYwaGbKoTjX7Fd/SI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":95857},"type":"module","engines":{"node":">=20"},"gitHead":"a49de3e19e784f88bea43a06bcfb82e3c2386aa5","mcpName":"io.github.mindstone/mcp-server-microsoft-mail","scripts":{"test":"vitest run","build":"shx rm -rf dist && tsc && shx chmod +x dist/index.js && npm run security:internal-refs","start":"node dist/index.js","watch":"tsc --watch","prepare":"npm run build","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test","security:internal-refs":"node scripts/check-internal-refs.mjs"},"_npmUser":{"name":"mindstone-engineering","email":"engineering@mindstone.com"},"repository":{"url":"git+https://github.com/mindstone/mcp-servers.git","type":"git","directory":"connectors/microsoft-mail"},"_npmVersion":"11.11.1","description":"Microsoft 365 Outlook Mail MCP server — read, search, send, reply, forward, draft, move, and delete email via Microsoft Graph","directories":{},"_nodeVersion":"25.8.2","dependencies":{"zod":"^3.23.0","@modelcontextprotocol/sdk":"^1.26.0","@mindstone/mcp-server-microsoft-shared":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.13.2","shx":"^0.3.4","vitest":"^4.1.3","typescript":"^5.8.2","@types/node":"^22","@vitest/coverage-v8":"^4.1.3","@mindstone/mcp-test-harness":"file:../../test-harness"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-microsoft-mail_0.1.0_1779223621652_0.008591472030009761","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@mindstone/mcp-server-microsoft-mail","version":"0.1.1","license":"FSL-1.1-MIT","_id":"@mindstone/mcp-server-microsoft-mail@0.1.1","maintainers":[{"name":"mindstone-engineering","email":"engineering@mindstone.com"}],"homepage":"https://github.com/mindstone/mcp-servers/tree/main/connectors/microsoft-mail","bugs":{"url":"https://github.com/mindstone/mcp-servers/issues"},"bin":{"mcp-server-microsoft-mail":"dist/index.js"},"dist":{"shasum":"356de230f399d9baf619c68d704da27f278d44ca","tarball":"https://registry.npmjs.org/@mindstone/mcp-server-microsoft-mail/-/mcp-server-microsoft-mail-0.1.1.tgz","fileCount":33,"integrity":"sha512-PgIpwndrz4ZhQorhGnlSe3fO/FmTM0T9236vNmICY+md7hZoz5bx21gwYMV1sNdbfhcybcO6y9Z3frSCyVL0gg==","signatures":[{"sig":"MEQCIC5sVeOLTahBTeClzq+/z/AzmqOUBlDA0y1mr4KuWQWEAiAk0dfOV9EL6NOOvM9uoQYK+mAks3Hk6IPD8oKjLJJGgg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":100123},"type":"module","engines":{"node":">=20"},"gitHead":"2318e6429c67600786dad9cc697f2cde0b94b3a8","mcpName":"io.github.mindstone/mcp-server-microsoft-mail","scripts":{"test":"vitest run","build":"shx rm -rf dist && tsc && shx chmod +x dist/index.js && npm run security:internal-refs","start":"node dist/index.js","watch":"tsc --watch","prepare":"npm run build","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test","security:internal-refs":"node scripts/check-internal-refs.mjs"},"_npmUser":{"name":"mindstone-engineering","email":"engineering@mindstone.com"},"repository":{"url":"git+https://github.com/mindstone/mcp-servers.git","type":"git","directory":"connectors/microsoft-mail"},"_npmVersion":"11.11.1","description":"Microsoft 365 Outlook mail via Graph: read, search, send, reply, forward, draft, move, delete.","directories":{},"_nodeVersion":"25.8.2","dependencies":{"zod":"^3.23.0","@modelcontextprotocol/sdk":"^1.26.0","@mindstone/mcp-server-microsoft-shared":"0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.13.2","shx":"^0.3.4","vitest":"^4.1.3","typescript":"^5.8.2","@types/node":"^22","@vitest/coverage-v8":"^4.1.3","@mindstone/mcp-test-harness":"file:../../test-harness"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-microsoft-mail_0.1.1_1779280993916_0.5241858744209724","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@mindstone/mcp-server-microsoft-mail","version":"0.1.2","license":"FSL-1.1-MIT","_id":"@mindstone/mcp-server-microsoft-mail@0.1.2","maintainers":[{"name":"mindstone-engineering","email":"engineering@mindstone.com"}],"homepage":"https://github.com/mindstone/mcp-servers/tree/main/connectors/microsoft-mail","bugs":{"url":"https://github.com/mindstone/mcp-servers/issues"},"bin":{"mcp-server-microsoft-mail":"dist/index.js"},"dist":{"shasum":"5f2765306172015383d4b7657e75c6c05809faae","tarball":"https://registry.npmjs.org/@mindstone/mcp-server-microsoft-mail/-/mcp-server-microsoft-mail-0.1.2.tgz","fileCount":21,"integrity":"sha512-Bo5yYi+1UCGxlWmvUbmmQnbp39mXKfT5pR9iiI+dr6KHrfAWvY1aS5mklhuqdds+Uxfph2LplV1Hlme7ZgyRSg==","signatures":[{"sig":"MEMCHxPzdvjtCAE4V9sapyEizqAdThQC3zJtYzPIx8gZXUgCIDJnmVAWLLNHH1s1oub0z/BVmIMFrHxyoYe9Dubi9N7W","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@mindstone%2fmcp-server-microsoft-mail@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":73148},"type":"module","_from":"file:mindstone-mcp-server-microsoft-mail-0.1.2.tgz","engines":{"node":">=20"},"mcpName":"io.github.mindstone/mcp-server-microsoft-mail","scripts":{"test":"vitest run","build":"shx rm -rf dist && tsc && shx chmod +x dist/index.js && npm run security:internal-refs","start":"node dist/index.js","watch":"tsc --watch","prepare":"npm run build","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test","security:internal-refs":"node scripts/check-internal-refs.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:311ef146-2fa0-4deb-909b-b755399f17d7"}},"_resolved":"/home/runner/work/mcp-servers/mcp-servers/mindstone-mcp-server-microsoft-mail-0.1.2.tgz","_integrity":"sha512-Bo5yYi+1UCGxlWmvUbmmQnbp39mXKfT5pR9iiI+dr6KHrfAWvY1aS5mklhuqdds+Uxfph2LplV1Hlme7ZgyRSg==","repository":{"url":"git+https://github.com/mindstone/mcp-servers.git","type":"git","directory":"connectors/microsoft-mail"},"_npmVersion":"11.16.0","description":"Microsoft 365 Outlook mail via Graph: read, search, send, reply, forward, draft, move, delete.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^3.23.0","@modelcontextprotocol/sdk":"^1.26.0","@mindstone/mcp-server-microsoft-shared":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.13.2","shx":"^0.3.4","vitest":"^4.1.3","typescript":"^5.8.2","@types/node":"^22","@vitest/coverage-v8":"^4.1.3","@mindstone/mcp-test-harness":"file:../../test-harness"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-microsoft-mail_0.1.2_1783092496827_0.38576180356283984","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@mindstone/mcp-server-microsoft-mail","version":"0.2.0","license":"FSL-1.1-MIT","_id":"@mindstone/mcp-server-microsoft-mail@0.2.0","maintainers":[{"name":"mindstone-engineering","email":"engineering@mindstone.com"}],"homepage":"https://github.com/mindstone/mcp-servers/tree/main/connectors/microsoft-mail","bugs":{"url":"https://github.com/mindstone/mcp-servers/issues"},"bin":{"mcp-server-microsoft-mail":"dist/index.js"},"dist":{"shasum":"a5fcc54afa592a3d8d577c9a9fbbde1f68034d85","tarball":"https://registry.npmjs.org/@mindstone/mcp-server-microsoft-mail/-/mcp-server-microsoft-mail-0.2.0.tgz","fileCount":25,"integrity":"sha512-C9HxVLalhd3e9wyQ+PHaN/UUtM/O8c1/EIlpcmOOegYSGoHnbV5U1udTZ60arvgDdLAavWIAr8HbNc+0Ruh3rA==","signatures":[{"sig":"MEUCIQC44Ii+RieYCDqy2oLBlZ1QJ1xdLIS9CyaWHBjFTTmYqQIgGbnlarYws2hq4Rzh9RW8Dz2zwGVfAw4ltTyL8+0Ty8A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@mindstone%2fmcp-server-microsoft-mail@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":150486},"type":"module","_from":"file:mindstone-mcp-server-microsoft-mail-0.2.0.tgz","engines":{"node":">=20"},"mcpName":"io.github.mindstone/mcp-server-microsoft-mail","scripts":{"test":"vitest run","build":"shx rm -rf dist && tsc && shx chmod +x dist/index.js && npm run security:internal-refs","start":"node dist/index.js","watch":"tsc --watch","prepare":"npm run build","pretest":"npm run compose:template:check","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test","compose:template":"node scripts/gen-compose-html.mjs","compose:template:check":"node scripts/gen-compose-html.mjs --check","security:internal-refs":"node scripts/check-internal-refs.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:311ef146-2fa0-4deb-909b-b755399f17d7"}},"_resolved":"/home/runner/work/mcp-servers/mcp-servers/mindstone-mcp-server-microsoft-mail-0.2.0.tgz","_integrity":"sha512-C9HxVLalhd3e9wyQ+PHaN/UUtM/O8c1/EIlpcmOOegYSGoHnbV5U1udTZ60arvgDdLAavWIAr8HbNc+0Ruh3rA==","repository":{"url":"git+https://github.com/mindstone/mcp-servers.git","type":"git","directory":"connectors/microsoft-mail"},"_npmVersion":"11.16.0","description":"Microsoft 365 Outlook mail via Graph: read, search, send, reply, forward, draft, move, delete.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^3.23.0","@modelcontextprotocol/sdk":"^1.26.0","@mindstone/mcp-server-microsoft-shared":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.13.2","shx":"^0.3.4","vitest":"^4.1.3","typescript":"^5.8.2","@types/node":"^22","@vitest/coverage-v8":"^4.1.3","@mindstone/mcp-app-compose":"file:../../packages/mcp-app-compose","@mindstone/mcp-test-harness":"file:../../test-harness"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-microsoft-mail_0.2.0_1785368900024_0.17771828240895493","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@mindstone/mcp-server-microsoft-mail","version":"0.3.0","mcpName":"io.github.mindstone/mcp-server-microsoft-mail","description":"Microsoft 365 Outlook mail via Graph: read, search, send, reply, forward, draft, move, delete.","license":"FSL-1.1-MIT","type":"module","bin":{"mcp-server-microsoft-mail":"dist/index.js"},"repository":{"type":"git","url":"git+https://github.com/mindstone/mcp-servers.git","directory":"connectors/microsoft-mail"},"homepage":"https://github.com/mindstone/mcp-servers/tree/main/connectors/microsoft-mail","publishConfig":{"access":"public"},"scripts":{"build":"shx rm -rf dist && tsc && shx chmod +x dist/index.js && npm run security:internal-refs","prepare":"npm run build","prepublishOnly":"npm run build && npm test","watch":"tsc --watch","start":"node dist/index.js","pretest":"npm run compose:template:check","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","compose:template":"node scripts/gen-compose-html.mjs","compose:template:check":"node scripts/gen-compose-html.mjs --check","security:internal-refs":"node scripts/check-internal-refs.mjs"},"dependencies":{"@mindstone/mcp-server-microsoft-shared":"^0.1.0","@modelcontextprotocol/sdk":"^1.26.0","zod":"^3.23.0"},"devDependencies":{"@mindstone/mcp-app-compose":"file:../../packages/mcp-app-compose","@mindstone/mcp-test-harness":"file:../../test-harness","@types/node":"^22","@vitest/coverage-v8":"^4.1.3","msw":"^2.13.2","shx":"^0.3.4","typescript":"^5.8.2","vitest":"^4.1.3"},"engines":{"node":">=20"},"_id":"@mindstone/mcp-server-microsoft-mail@0.3.0","bugs":{"url":"https://github.com/mindstone/mcp-servers/issues"},"_integrity":"sha512-R+XXeoUaG/UlIn+5oOl1t5urcCHC+PjSudLKDkXxkC9+DbNypm3iHKMqDsoeFTqtFouyLF/7yl38llRifDW7JQ==","_resolved":"/home/runner/work/mcp-servers/mcp-servers/mindstone-mcp-server-microsoft-mail-0.3.0.tgz","_from":"file:mindstone-mcp-server-microsoft-mail-0.3.0.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-R+XXeoUaG/UlIn+5oOl1t5urcCHC+PjSudLKDkXxkC9+DbNypm3iHKMqDsoeFTqtFouyLF/7yl38llRifDW7JQ==","shasum":"639e7ff52392143601150c53eb9f1ec7ab706a41","tarball":"https://registry.npmjs.org/@mindstone/mcp-server-microsoft-mail/-/mcp-server-microsoft-mail-0.3.0.tgz","fileCount":25,"unpackedSize":222174,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@mindstone%2fmcp-server-microsoft-mail@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDKajcdAI4mO6REE3TBYKO7dn5GsoWiMfQM/f22C6UwJwIhAIzEaVU2cjt+sw4Ff/vWsgcU08o4YEASoNByH6Ka/Gi7"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:311ef146-2fa0-4deb-909b-b755399f17d7"}},"directories":{},"maintainers":[{"name":"mindstone-engineering","email":"engineering@mindstone.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-microsoft-mail_0.3.0_1786091661668_0.37046834378421956"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-19T20:47:01.436Z","modified":"2026-08-07T08:34:22.139Z","0.1.0":"2026-05-19T20:47:01.799Z","0.1.1":"2026-05-20T12:43:14.056Z","0.1.2":"2026-07-03T15:28:16.964Z","0.2.0":"2026-07-29T23:48:20.202Z","0.3.0":"2026-08-07T08:34:21.810Z"},"bugs":{"url":"https://github.com/mindstone/mcp-servers/issues"},"license":"FSL-1.1-MIT","homepage":"https://github.com/mindstone/mcp-servers/tree/main/connectors/microsoft-mail","repository":{"type":"git","url":"git+https://github.com/mindstone/mcp-servers.git","directory":"connectors/microsoft-mail"},"description":"Microsoft 365 Outlook mail via Graph: read, search, send, reply, forward, draft, move, delete.","maintainers":[{"name":"mindstone-engineering","email":"engineering@mindstone.com"}],"readme":"# @mindstone/mcp-server-microsoft-mail\n\n[![npm version](https://img.shields.io/npm/v/@mindstone/mcp-server-microsoft-mail.svg)](https://www.npmjs.com/package/@mindstone/mcp-server-microsoft-mail)\n[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](./LICENSE)\n\nMicrosoft 365 Outlook Mail MCP server — list, search, read, send, reply, forward, draft, move, and delete email, download attachments, read threads, triage (read/flag), and manage out-of-office replies via the Microsoft Graph API.\n\n*Cohort-style Microsoft 365 mail MCP. Host owns the OAuth flow, this server reads per-account tokens off disk, and each tool fails closed with a structured `auth_required` envelope so the host can drive reauth.*\n\n## Status\n\n- **Version:** [0.3.0](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-microsoft-mail)\n- **Auth:** OAuth (host-orchestrated) ([`MS_CLIENT_ID`](./server.json))\n- **Tools:** [22](./src/tools.ts) (messages, folders, drafts, attachments, threads, settings)\n- **Surface:** cloud-api\n- **Machine-readable:** [`STATUS.json`](./STATUS.json)\n- **Shared library:** [`@mindstone/mcp-server-microsoft-shared`](https://www.npmjs.com/package/@mindstone/mcp-server-microsoft-shared)\n\n## Why this exists\n\nWhen we ported this in May 2026, Microsoft's own [Graph MCP](https://github.com/microsoft/mcp) lineup did not yet ship a stand-alone Outlook Mail server, and the community options at the time each ran their own browser-callback server during OAuth — which our host application already does, with credentials it has already negotiated for the rest of the cohort. We pulled the bundled connector out of MindstoneRebel as a 1:1 port so the same five-connector Microsoft 365 cohort (mail, calendar, files, teams, SharePoint) shares a single OAuth surface, a single shared-library package for token persistence, request timeouts, and the structured `auth_required` envelope the host already knows how to recover from. This connector owns the cohort's authentication tool (`authenticate_microsoft_account`); the other four connectors reuse the credentials it negotiates.\n\n## Example interaction\n\n> \"List my five most recent unread emails from Alice and reply to the latest one with 'thanks, will read tonight'.\"\n\nTools the host calls:\n1. `search_emails` — `from:alice@example.com isRead:false`, top 5.\n2. `reply_to_email` — sends a reply on the top-result message ID with the supplied body.\n\nResponse (trimmed):\n\n```json\n{\n  \"matches\": [\n    {\n      \"id\": \"AAMkAD...\",\n      \"subject\": \"Q3 planning\",\n      \"from\": \"alice@example.com\",\n      \"receivedDateTime\": \"2026-05-19T09:14:11Z\"\n    }\n  ],\n  \"reply\": {\n    \"id\": \"AAMkAD...\",\n    \"isDraft\": false\n  }\n}\n```\n\n## Requirements\n\n- Node.js 20+\n- npm\n- A host application that performs the Microsoft OAuth flow and writes per-account token files into `${MS_CONFIG_DIR}/credentials/${sanitised-email}.token.json` and an `${MS_CONFIG_DIR}/accounts.json` index. This server reads those files; it does not initiate OAuth itself.\n\n<!-- BEGIN INSTALL_LINKS: do not edit by hand; regenerated by scripts/gen-install-links.mjs -->\n## One-click install\n\n[![Add to Cursor](https://img.shields.io/badge/Add_to_Cursor-black?style=for-the-badge&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=Microsoft%20365%20Mail&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtaW5kc3RvbmUvbWNwLXNlcnZlci1taWNyb3NvZnQtbWFpbCJdLCJlbnYiOnsiTVNfQ0xJRU5UX0lEIjoiIiwiTVNfQ09ORklHX0RJUiI6IiIsIk1TX01DUF9QQUNLQUdFX0lEIjoiTWljcm9zb2Z0MzY1TWFpbCIsIk1JQ1JPU09GVF9SRVFVRVNUX1RJTUVPVVRfTVMiOiI2MDAwMCJ9fQ)\n[![Add to VS Code](https://img.shields.io/badge/Add_to_VS_Code-007ACC?style=for-the-badge&logo=visual-studio-code&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22Microsoft%20365%20Mail%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40mindstone%2Fmcp-server-microsoft-mail%22%5D%2C%22env%22%3A%7B%22MS_CLIENT_ID%22%3A%22%22%2C%22MS_CONFIG_DIR%22%3A%22%22%2C%22MS_MCP_PACKAGE_ID%22%3A%22Microsoft365Mail%22%2C%22MICROSOFT_REQUEST_TIMEOUT_MS%22%3A%2260000%22%7D%7D)\n[![Add to VS Code Insiders](https://img.shields.io/badge/Add_to_VS_Code_Insiders-24bfa5?style=for-the-badge&logo=visual-studio-code&logoColor=white)](vscode-insiders:mcp/install?%7B%22name%22%3A%22Microsoft%20365%20Mail%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40mindstone%2Fmcp-server-microsoft-mail%22%5D%2C%22env%22%3A%7B%22MS_CLIENT_ID%22%3A%22%22%2C%22MS_CONFIG_DIR%22%3A%22%22%2C%22MS_MCP_PACKAGE_ID%22%3A%22Microsoft365Mail%22%2C%22MICROSOFT_REQUEST_TIMEOUT_MS%22%3A%2260000%22%7D%7D)\n\nAfter clicking the button, your host will prompt you to fill: `MS_CLIENT_ID`, `MS_CONFIG_DIR`, `MS_MCP_PACKAGE_ID`, `MICROSOFT_REQUEST_TIMEOUT_MS`.\n\n<details>\n<summary>Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (Microsoft 365 Mail)</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"Microsoft 365 Mail\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@mindstone/mcp-server-microsoft-mail\"\n      ],\n      \"env\": {\n        \"MS_CLIENT_ID\": \"\",\n        \"MS_CONFIG_DIR\": \"\",\n        \"MS_MCP_PACKAGE_ID\": \"Microsoft365Mail\",\n        \"MICROSOFT_REQUEST_TIMEOUT_MS\": \"60000\"\n      }\n    }\n  }\n}\n```\n\n</details>\n<!-- END INSTALL_LINKS -->\n\n## Quick Start\n\n### Install & build\n\n```bash\ncd <path-to-repo>/connectors/microsoft-mail\nnpm install\nnpm run build\n```\n\n### npx (once published)\n\n```bash\nnpx -y @mindstone/mcp-server-microsoft-mail\n```\n\n### Local\n\n```bash\nnode dist/index.js\n```\n\n## Configuration\n\nThis server runs alongside a host application that owns the Microsoft 365 OAuth flow. The host writes credentials to disk; this server reads them.\n\n### Required environment variables\n\n| Name | Description |\n| ---- | ----------- |\n| `MS_CLIENT_ID` | Microsoft Entra (Azure AD) application client ID. |\n| `MS_CONFIG_DIR` | Path to the per-user Microsoft config directory (`credentials/`, `accounts.json`). |\n\n### Optional environment variables\n\n| Name | Description | Default |\n| ---- | ----------- | ------- |\n| `MS_ACCOUNT_EMAIL` | Account email when running in multi-account per-instance mode. | First account in `accounts.json`. |\n| `MS_MCP_PACKAGE_ID` | Logical package ID surfaced in error responses. | `Microsoft365Mail` |\n| `MICROSOFT_REQUEST_TIMEOUT_MS` | Override the upstream Microsoft Graph request timeout (max `300000` ms). | `60000` |\n| `MICROSOFT_DISABLE_REFRESH` | Set to `1` to disable token refresh on this surface. Tools fail closed with the structured `auth_required` response so the host can drive reauth. Cloud surfaces set this to `1`. | unset |\n| `MCP_WORKSPACE_PATH` | Workspace root where `download_attachment` saves files. | OS temp directory |\n\n## Host configuration examples\n\n### Claude Desktop / Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"Microsoft365Mail\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@mindstone/mcp-server-microsoft-mail\"],\n      \"env\": {\n        \"MS_CLIENT_ID\": \"your-entra-application-client-id\",\n        \"MS_CONFIG_DIR\": \"/absolute/path/to/microsoft-config\"\n      }\n    }\n  }\n}\n```\n\nUntil the host has written `${MS_CONFIG_DIR}/credentials/<account>.token.json` and `${MS_CONFIG_DIR}/accounts.json`, every tool call returns the structured `auth_required` response (the host's MCP service recognises this shape and dispatches to its registered Microsoft 365 OAuth orchestrator).\n\n### Local development (no npm publish needed)\n\n```json\n{\n  \"mcpServers\": {\n    \"Microsoft365Mail\": {\n      \"command\": \"node\",\n      \"args\": [\"<path-to-repo>/connectors/microsoft-mail/dist/index.js\"],\n      \"env\": {\n        \"MS_CLIENT_ID\": \"your-entra-application-client-id\",\n        \"MS_CONFIG_DIR\": \"/absolute/path/to/microsoft-config\"\n      }\n    }\n  }\n}\n```\n\n## Tools (22)\n\n| Tool | Description |\n| ---- | ----------- |\n| `authenticate_microsoft_account` | Emit the structured `auth_required` handoff so the host runs the Microsoft 365 OAuth flow. |\n| `list_emails` | List emails in a folder, ordered by most recent (see ordering note below). |\n| `get_email` | Read a single email by message ID. |\n| `list_attachments` | List attachment metadata (ID, name, type, size) for a message. |\n| `download_attachment` | Save a file attachment into the workspace (or OS temp directory). |\n| `send_email` | Send a new email message (supports CC and BCC). |\n| `compose_email` | Open an editable draft in an interactive compose view; nothing is sent until the user clicks Send. |\n| `search_emails` | Search emails using Microsoft Search syntax. |\n| `get_conversation` | List messages in a thread, oldest first (see ordering note below). |\n| `reply_to_email` | Reply (or reply-all) to an existing email. |\n| `forward_email` | Forward an email to additional recipients. |\n| `delete_email` | Move an email to Deleted Items, or hard-delete it. |\n| `list_folders` | List mail folders. |\n| `move_email` | Move an email to a different folder. |\n| `create_reply_draft` | Save a draft reply to an existing email. |\n| `create_draft` | Save a new standalone draft email (supports CC and BCC). |\n| `send_draft` | Send an existing draft. |\n| `update_draft` | Update a draft's subject, body, recipients, or importance. |\n| `mark_email_read` | Mark an email as read or unread. |\n| `set_email_flag` | Flag an email for follow-up, complete it, or clear the flag. |\n| `get_automatic_replies` | Read the out-of-office configuration (requires `MailboxSettings.Read`). |\n| `set_automatic_replies` | Turn out-of-office replies on/off or schedule them (requires `MailboxSettings.ReadWrite`). |\n\n### Graph permissions\n\nMail tools run on the `Mail.ReadWrite` + `Mail.Send` delegated grants. The automatic-replies tools additionally need `MailboxSettings.Read` / `MailboxSettings.ReadWrite`; in many organizations an administrator must approve that permission, and the tools return a guidance envelope (rather than a raw Graph 403) when the connected account lacks it.\n\n### Ordering and validation notes\n\n- **Filtered listing is page-local.** Microsoft Graph rejects `$filter` combined with `$orderby`, so when `list_emails` is called with a `filter` (and always for `get_conversation`) the connector sorts only the returned page client-side: Graph applies `$top` first, so the result is the sorted view of whichever page Graph returned, not a globally ordered scan of the mailbox. Unfiltered `list_emails` still sorts server-side.\n- **Recipients are validated.** `to`/`cc`/`bcc` entries must be email addresses (trimmed, max 254 chars, max 500 recipients per field); invalid entries are rejected before any Graph call.\n- **Scheduled out-of-office windows** require ISO 8601 date-times; explicit offsets are converted to UTC (zone-less values are treated as UTC) and the start must be earlier than the end.\n\n## Security notes\n\n- Token files are written by the host with mode `0600`; this server reads them via the cohort-shared library, which fails closed on malformed files.\n- `MICROSOFT_DISABLE_REFRESH=1` is the default on cloud surfaces so the desktop session remains the sole refresh-token authority and avoids racing for single-use refresh tokens.\n- Successful tool responses drop the OSS-only `ok:true` wrapper to match the bundled `successResult` shape; manual validation/business errors return `isError:true` with a `{ ok:false, error, action_required, next_step }` payload so the host's recovery layer can act on them.\n- Per-tool Graph calls run under a composed caller + cohort timeout signal via `.options({signal})` plus a `Promise.race` wrapper for defence-in-depth.\n- `download_attachment` writes only inside `MCP_WORKSPACE_PATH` (or the OS temp directory when unset), rejects anything but a plain filename, and caps downloads at 25 MB. Attachment bytes are streamed from the `$value` endpoint with a hard byte cap (never fully materialized past the limit), metadata is streamed with a hard 1 MB cap for the same reason, and the workspace root is canonicalised (symlinks resolved) before anything is written. Each download is saved into a fresh, private staging directory created atomically (`fs.mkdtemp`, mode `0700`) directly under the canonical workspace root, carrying over only the attachment file name; the reported `savedTo` points inside that staging directory. Because the connector invents the directory name, there is no validated user-visible pathname to pre-plant, rename, or symlink-swap between validation and the write syscall, so the parent-directory check-then-use race is removed by construction — on every platform, with no descriptor-relative APIs. The file itself is created with an exclusive open (`O_CREAT|O_EXCL`, mode `0600`), so overwrite is impossible and a pre-existing same-named file or symlink is never touched; a failed write removes its whole staging directory, leaving no residue. Attacker-controlled attachment fields (name, type, content type) are wrapped in untrusted-content envelopes wherever they surface as text, including error paths. `savedTo` necessarily reports the real file path (the host needs it to open the file), but the human-facing `message` names only the connector-invented staging directory, so the attacker-authored file name is never echoed as trusted prose.\n- Error guidance for non-authentication failures never recommends re-authentication: Graph 403 permission denials are answered with connector-local guidance explaining that re-authenticating the same account will not help, and upstream Graph error text is enveloped as untrusted content before it reaches the model.\n\n## Licence\n\n[FSL-1.1-MIT](./LICENSE) — Functional Source License, Version 1.1, with MIT future licence. Free for non-competing use; relicenses to MIT on the converter date in `LICENSE`.\n","readmeFilename":"README.md"}