msoutlook-mcp 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +41 -13
  3. package/package.json +2 -2
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Shayan Khaksar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,15 +1,29 @@
1
1
  # msoutlook-mcp
2
2
 
3
- MCP server for Microsoft Outlook Web — no app registration required.
3
+ [![npm version](https://img.shields.io/npm/v/msoutlook-mcp.svg)](https://www.npmjs.com/package/msoutlook-mcp)
4
+ [![npm downloads](https://img.shields.io/npm/dm/msoutlook-mcp.svg)](https://www.npmjs.com/package/msoutlook-mcp)
5
+ [![node](https://img.shields.io/node/v/msoutlook-mcp.svg)](https://www.npmjs.com/package/msoutlook-mcp)
6
+ [![license](https://img.shields.io/npm/l/msoutlook-mcp.svg)](./LICENSE)
4
7
 
5
- Uses your existing Outlook Web session (the same way [msteams-mcp](https://github.com/m0nkmaster/msteams-mcp) uses the Teams web session). Opens a browser once for login, then caches tokens and refreshes them automatically.
8
+ MCP server for Microsoft Outlook Web. No app registration required.
9
+
10
+ Give any MCP client (Claude, Cursor, Devin, ...) read and write access to your Outlook mail, calendar, and contacts. It works by reusing your existing Outlook Web session, the same way [msteams-mcp](https://github.com/m0nkmaster/msteams-mcp) reuses the Teams web session: you sign in once in a browser, then tokens are cached and refreshed automatically.
11
+
12
+ ## Why
13
+
14
+ Most Outlook MCP servers make you register an Azure AD application, grant admin consent, and manage client secrets. This one needs none of that. It uses Outlook Web's own first-party client ID, so your access is exactly what your account already has, and nothing is exposed beyond your own machine.
15
+
16
+ - No Azure app registration, admin consent, or client secrets
17
+ - Cross-platform (macOS, Linux, Windows) with automatic browser detection
18
+ - Tokens encrypted at rest; refreshed silently in the background
19
+ - 30 tools across mail, calendar, contacts, and people
6
20
 
7
21
  ## How it works
8
22
 
9
23
  Microsoft Outlook Web (OWA) uses MSAL to store OAuth tokens in `localStorage`. This server:
10
24
 
11
25
  1. Opens a browser to `outlook.office.com` via Playwright
12
- 2. Extracts the MSAL token cache from `localStorage` — using OWA's own first-party client ID (`9199bf20-a13f-4107-85dc-02114787ef48`)
26
+ 2. Extracts the MSAL token cache from `localStorage`, using OWA's own first-party client ID (`9199bf20-a13f-4107-85dc-02114787ef48`)
13
27
  3. Caches the access token, refresh token, and session state in `~/.msoutlook-mcp-server/` (AES-256-GCM encrypted)
14
28
  4. Refreshes tokens automatically using the refresh token (HTTP, no browser) or headless browser as fallback
15
29
 
@@ -28,7 +42,7 @@ No Azure app registration. No admin consent. No client secrets. Your access is l
28
42
  }
29
43
  ```
30
44
 
31
- Then run `outlook_login` from your MCP client to open the browser and authenticate.
45
+ Then run `outlook_login` from your MCP client. On first use a browser opens so you can sign in; after that, logins are silent and no browser appears. Do not close the window manually, it closes itself once you are signed in.
32
46
 
33
47
  ## Tools
34
48
 
@@ -86,9 +100,9 @@ Then run `outlook_login` from your MCP client to open the browser and authentica
86
100
 
87
101
  Session files are stored encrypted in `~/.msoutlook-mcp-server/`:
88
102
 
89
- - `session-state.json` — Playwright browser session (cookies + localStorage)
90
- - `token-cache.json` — Extracted and cached tokens
91
- - `browser-profile/` — Persistent browser profile for headless refresh
103
+ - `session-state.json`: Playwright browser session (cookies + localStorage)
104
+ - `token-cache.json`: Extracted and cached tokens
105
+ - `browser-profile/`: Persistent browser profile for headless refresh
92
106
 
93
107
  If your session expires, run `outlook_login` again.
94
108
 
@@ -96,8 +110,8 @@ If your session expires, run `outlook_login` again.
96
110
 
97
111
  Tokens are refreshed automatically:
98
112
 
99
- 1. **HTTP refresh** (fast, no browser) — uses the cached refresh token with OWA's client ID
100
- 2. **Headless browser refresh** — fallback if HTTP refresh fails; opens a headless Edge window to silently re-acquire tokens from the saved browser session
113
+ 1. **HTTP refresh** (fast, no browser): uses the cached refresh token with OWA's client ID
114
+ 2. **Headless browser refresh**: fallback if HTTP refresh fails; opens a headless Edge window to silently re-acquire tokens from the saved browser session
101
115
 
102
116
  ## Requirements
103
117
 
@@ -111,16 +125,16 @@ Tokens are refreshed automatically:
111
125
  |---------|-------|-------|---------|
112
126
  | Browser auto-detection | System default (Edge/Chrome) | Chrome fallback | Edge (pre-installed) |
113
127
  | SSO cookie import | ✅ Chrome + Edge via Keychain | ✅ Chrome + Edge via libsecret / `"peanuts"` fallback | ✅ Edge via DPAPI (PowerShell) |
114
- | Windows Chrome 127+ cookies | — | — | ⚠️ App-Bound Encryption — not supported. Use Edge instead. |
128
+ | Windows Chrome 127+ cookies | n/a | n/a | ⚠️ App-Bound Encryption (not supported). Use Edge instead. |
115
129
  | Headed browser fallback | ✅ | ✅ | ✅ |
116
130
 
117
- Cookie import is a best-effort optimisation. If it cannot run (e.g. no matching browser installed, Keychain denied), the MCP falls back to opening a headed browser where you sign in once manually — the session then persists.
131
+ Cookie import is a best-effort optimisation. If it cannot run (e.g. no matching browser installed, Keychain denied), the MCP falls back to opening a headed browser where you sign in once manually, and the session then persists.
118
132
 
119
133
  ## Security notes
120
134
 
121
- - Uses the same auth as the Outlook web client — your access is limited to what your account can do
135
+ - Uses the same auth as the Outlook web client, so your access is limited to what your account can do
122
136
  - Tokens are encrypted at rest (AES-256-GCM with a machine-derived key)
123
- - Uses undocumented internal APIs — Microsoft may change these without notice
137
+ - Uses undocumented internal APIs, which Microsoft may change without notice
124
138
  - Always confirm email content with the user before sending
125
139
 
126
140
  ## Environment variables
@@ -132,3 +146,17 @@ Cookie import is a best-effort optimisation. If it cannot run (e.g. no matching
132
146
  | `MSOUTLOOK_CHROME_PROFILE` | Pin a specific Chrome profile dir for cookie import (e.g. `Profile 1`). Defaults to `Default`. |
133
147
  | `MSOUTLOOK_EDGE_PROFILE` | Pin a specific Edge profile dir for cookie import (e.g. `Profile 1`). Defaults to `Default`. |
134
148
  | `MSOUTLOOK_SKIP_COOKIE_IMPORT=true` | Skip importing SSO cookies from your real browser (avoids the one-time Keychain/keyring prompt). You'll sign in once manually in the browser; the persistent profile then remembers the session. |
149
+
150
+ ## Troubleshooting
151
+
152
+ **A macOS Keychain prompt appears on first login.** That is the cookie import reading your browser's session. Click "Always Allow" once and it never prompts again. If you would rather not grant it, set `MSOUTLOOK_SKIP_COOKIE_IMPORT=true` and sign in manually the first time instead.
153
+
154
+ **Login says it failed but the browser showed my inbox.** Run `outlook_login` again and let the window close on its own. If it persists, run with `MSOUTLOOK_DEBUG=true` and check the stderr logs.
155
+
156
+ **It opens the wrong browser.** Set `MSOUTLOOK_BROWSER=chrome` or `MSOUTLOOK_BROWSER=msedge` to force one. Only Chromium-based browsers (Chrome, Edge) are supported; Safari and Firefox fall back to Chrome/Edge.
157
+
158
+ **Tokens stopped working after a long break.** Refresh tokens last around 90 days. Run `outlook_login` to re-authenticate.
159
+
160
+ ## License
161
+
162
+ MIT. See [LICENSE](./LICENSE).
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "msoutlook-mcp",
3
- "version": "0.1.1",
4
- "description": "MCP server for Microsoft Outlook web — no app registration required, uses your existing Outlook session",
3
+ "version": "0.1.3",
4
+ "description": "MCP server for Microsoft Outlook web. No app registration required, uses your existing Outlook session.",
5
5
  "keywords": [
6
6
  "mcp",
7
7
  "outlook",