@jbctechsolutions/mcp-outlook-mac 1.0.0

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 (235) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +358 -0
  3. package/dist/applescript/account-repository.d.ts +29 -0
  4. package/dist/applescript/account-repository.d.ts.map +1 -0
  5. package/dist/applescript/account-repository.js +34 -0
  6. package/dist/applescript/account-repository.js.map +1 -0
  7. package/dist/applescript/account-scripts.d.ts +22 -0
  8. package/dist/applescript/account-scripts.d.ts.map +1 -0
  9. package/dist/applescript/account-scripts.js +176 -0
  10. package/dist/applescript/account-scripts.js.map +1 -0
  11. package/dist/applescript/calendar-manager.d.ts +45 -0
  12. package/dist/applescript/calendar-manager.d.ts.map +1 -0
  13. package/dist/applescript/calendar-manager.js +88 -0
  14. package/dist/applescript/calendar-manager.js.map +1 -0
  15. package/dist/applescript/calendar-writer.d.ts +38 -0
  16. package/dist/applescript/calendar-writer.d.ts.map +1 -0
  17. package/dist/applescript/calendar-writer.js +90 -0
  18. package/dist/applescript/calendar-writer.js.map +1 -0
  19. package/dist/applescript/content-readers.d.ts +93 -0
  20. package/dist/applescript/content-readers.d.ts.map +1 -0
  21. package/dist/applescript/content-readers.js +299 -0
  22. package/dist/applescript/content-readers.js.map +1 -0
  23. package/dist/applescript/executor.d.ts +62 -0
  24. package/dist/applescript/executor.d.ts.map +1 -0
  25. package/dist/applescript/executor.js +164 -0
  26. package/dist/applescript/executor.js.map +1 -0
  27. package/dist/applescript/index.d.ts +16 -0
  28. package/dist/applescript/index.d.ts.map +1 -0
  29. package/dist/applescript/index.js +25 -0
  30. package/dist/applescript/index.js.map +1 -0
  31. package/dist/applescript/mail-sender.d.ts +30 -0
  32. package/dist/applescript/mail-sender.d.ts.map +1 -0
  33. package/dist/applescript/mail-sender.js +53 -0
  34. package/dist/applescript/mail-sender.js.map +1 -0
  35. package/dist/applescript/parser.d.ts +215 -0
  36. package/dist/applescript/parser.d.ts.map +1 -0
  37. package/dist/applescript/parser.js +431 -0
  38. package/dist/applescript/parser.js.map +1 -0
  39. package/dist/applescript/repository.d.ts +58 -0
  40. package/dist/applescript/repository.d.ts.map +1 -0
  41. package/dist/applescript/repository.js +417 -0
  42. package/dist/applescript/repository.js.map +1 -0
  43. package/dist/applescript/scripts.d.ts +242 -0
  44. package/dist/applescript/scripts.d.ts.map +1 -0
  45. package/dist/applescript/scripts.js +1300 -0
  46. package/dist/applescript/scripts.js.map +1 -0
  47. package/dist/approval/hash.d.ts +26 -0
  48. package/dist/approval/hash.d.ts.map +1 -0
  49. package/dist/approval/hash.js +28 -0
  50. package/dist/approval/hash.js.map +1 -0
  51. package/dist/approval/index.d.ts +9 -0
  52. package/dist/approval/index.d.ts.map +1 -0
  53. package/dist/approval/index.js +8 -0
  54. package/dist/approval/index.js.map +1 -0
  55. package/dist/approval/token-manager.d.ts +48 -0
  56. package/dist/approval/token-manager.d.ts.map +1 -0
  57. package/dist/approval/token-manager.js +100 -0
  58. package/dist/approval/token-manager.js.map +1 -0
  59. package/dist/approval/types.d.ts +40 -0
  60. package/dist/approval/types.d.ts.map +1 -0
  61. package/dist/approval/types.js +8 -0
  62. package/dist/approval/types.js.map +1 -0
  63. package/dist/config.d.ts +23 -0
  64. package/dist/config.d.ts.map +1 -0
  65. package/dist/config.js +38 -0
  66. package/dist/config.js.map +1 -0
  67. package/dist/database/connection.d.ts +73 -0
  68. package/dist/database/connection.d.ts.map +1 -0
  69. package/dist/database/connection.js +126 -0
  70. package/dist/database/connection.js.map +1 -0
  71. package/dist/database/index.d.ts +7 -0
  72. package/dist/database/index.d.ts.map +1 -0
  73. package/dist/database/index.js +7 -0
  74. package/dist/database/index.js.map +1 -0
  75. package/dist/database/queries.d.ts +89 -0
  76. package/dist/database/queries.d.ts.map +1 -0
  77. package/dist/database/queries.js +422 -0
  78. package/dist/database/queries.js.map +1 -0
  79. package/dist/database/repository.d.ts +188 -0
  80. package/dist/database/repository.d.ts.map +1 -0
  81. package/dist/database/repository.js +187 -0
  82. package/dist/database/repository.js.map +1 -0
  83. package/dist/graph/auth/config.d.ts +33 -0
  84. package/dist/graph/auth/config.d.ts.map +1 -0
  85. package/dist/graph/auth/config.js +53 -0
  86. package/dist/graph/auth/config.js.map +1 -0
  87. package/dist/graph/auth/device-code-flow.d.ts +51 -0
  88. package/dist/graph/auth/device-code-flow.d.ts.map +1 -0
  89. package/dist/graph/auth/device-code-flow.js +176 -0
  90. package/dist/graph/auth/device-code-flow.js.map +1 -0
  91. package/dist/graph/auth/index.d.ts +9 -0
  92. package/dist/graph/auth/index.d.ts.map +1 -0
  93. package/dist/graph/auth/index.js +9 -0
  94. package/dist/graph/auth/index.js.map +1 -0
  95. package/dist/graph/auth/token-cache.d.ts +43 -0
  96. package/dist/graph/auth/token-cache.d.ts.map +1 -0
  97. package/dist/graph/auth/token-cache.js +99 -0
  98. package/dist/graph/auth/token-cache.js.map +1 -0
  99. package/dist/graph/client/cache.d.ts +65 -0
  100. package/dist/graph/client/cache.d.ts.map +1 -0
  101. package/dist/graph/client/cache.js +109 -0
  102. package/dist/graph/client/cache.js.map +1 -0
  103. package/dist/graph/client/graph-client.d.ts +150 -0
  104. package/dist/graph/client/graph-client.d.ts.map +1 -0
  105. package/dist/graph/client/graph-client.js +538 -0
  106. package/dist/graph/client/graph-client.js.map +1 -0
  107. package/dist/graph/client/index.d.ts +8 -0
  108. package/dist/graph/client/index.d.ts.map +1 -0
  109. package/dist/graph/client/index.js +8 -0
  110. package/dist/graph/client/index.js.map +1 -0
  111. package/dist/graph/content-readers.d.ts +102 -0
  112. package/dist/graph/content-readers.d.ts.map +1 -0
  113. package/dist/graph/content-readers.js +327 -0
  114. package/dist/graph/content-readers.js.map +1 -0
  115. package/dist/graph/index.d.ts +14 -0
  116. package/dist/graph/index.d.ts.map +1 -0
  117. package/dist/graph/index.js +19 -0
  118. package/dist/graph/index.js.map +1 -0
  119. package/dist/graph/mailbox-adapter.d.ts +25 -0
  120. package/dist/graph/mailbox-adapter.d.ts.map +1 -0
  121. package/dist/graph/mailbox-adapter.js +56 -0
  122. package/dist/graph/mailbox-adapter.js.map +1 -0
  123. package/dist/graph/mappers/contact-mapper.d.ts +10 -0
  124. package/dist/graph/mappers/contact-mapper.d.ts.map +1 -0
  125. package/dist/graph/mappers/contact-mapper.js +19 -0
  126. package/dist/graph/mappers/contact-mapper.js.map +1 -0
  127. package/dist/graph/mappers/email-mapper.d.ts +10 -0
  128. package/dist/graph/mappers/email-mapper.d.ts.map +1 -0
  129. package/dist/graph/mappers/email-mapper.js +43 -0
  130. package/dist/graph/mappers/email-mapper.js.map +1 -0
  131. package/dist/graph/mappers/event-mapper.d.ts +10 -0
  132. package/dist/graph/mappers/event-mapper.d.ts.map +1 -0
  133. package/dist/graph/mappers/event-mapper.js +28 -0
  134. package/dist/graph/mappers/event-mapper.js.map +1 -0
  135. package/dist/graph/mappers/folder-mapper.d.ts +18 -0
  136. package/dist/graph/mappers/folder-mapper.d.ts.map +1 -0
  137. package/dist/graph/mappers/folder-mapper.js +50 -0
  138. package/dist/graph/mappers/folder-mapper.js.map +1 -0
  139. package/dist/graph/mappers/index.d.ts +12 -0
  140. package/dist/graph/mappers/index.d.ts.map +1 -0
  141. package/dist/graph/mappers/index.js +12 -0
  142. package/dist/graph/mappers/index.js.map +1 -0
  143. package/dist/graph/mappers/task-mapper.d.ts +16 -0
  144. package/dist/graph/mappers/task-mapper.d.ts.map +1 -0
  145. package/dist/graph/mappers/task-mapper.js +26 -0
  146. package/dist/graph/mappers/task-mapper.js.map +1 -0
  147. package/dist/graph/mappers/utils.d.ts +75 -0
  148. package/dist/graph/mappers/utils.d.ts.map +1 -0
  149. package/dist/graph/mappers/utils.js +130 -0
  150. package/dist/graph/mappers/utils.js.map +1 -0
  151. package/dist/graph/repository.d.ts +112 -0
  152. package/dist/graph/repository.d.ts.map +1 -0
  153. package/dist/graph/repository.js +549 -0
  154. package/dist/graph/repository.js.map +1 -0
  155. package/dist/index.d.ts +17 -0
  156. package/dist/index.d.ts.map +1 -0
  157. package/dist/index.js +1821 -0
  158. package/dist/index.js.map +1 -0
  159. package/dist/parsers/html-stripper.d.ts +43 -0
  160. package/dist/parsers/html-stripper.d.ts.map +1 -0
  161. package/dist/parsers/html-stripper.js +175 -0
  162. package/dist/parsers/html-stripper.js.map +1 -0
  163. package/dist/parsers/index.d.ts +8 -0
  164. package/dist/parsers/index.d.ts.map +1 -0
  165. package/dist/parsers/index.js +8 -0
  166. package/dist/parsers/index.js.map +1 -0
  167. package/dist/parsers/olk15.d.ts +99 -0
  168. package/dist/parsers/olk15.d.ts.map +1 -0
  169. package/dist/parsers/olk15.js +364 -0
  170. package/dist/parsers/olk15.js.map +1 -0
  171. package/dist/tools/calendar.d.ts +203 -0
  172. package/dist/tools/calendar.d.ts.map +1 -0
  173. package/dist/tools/calendar.js +251 -0
  174. package/dist/tools/calendar.js.map +1 -0
  175. package/dist/tools/contacts.d.ts +89 -0
  176. package/dist/tools/contacts.d.ts.map +1 -0
  177. package/dist/tools/contacts.js +129 -0
  178. package/dist/tools/contacts.js.map +1 -0
  179. package/dist/tools/index.d.ts +12 -0
  180. package/dist/tools/index.d.ts.map +1 -0
  181. package/dist/tools/index.js +18 -0
  182. package/dist/tools/index.js.map +1 -0
  183. package/dist/tools/mail.d.ts +83 -0
  184. package/dist/tools/mail.d.ts.map +1 -0
  185. package/dist/tools/mail.js +217 -0
  186. package/dist/tools/mail.js.map +1 -0
  187. package/dist/tools/mailbox-organization.d.ts +337 -0
  188. package/dist/tools/mailbox-organization.d.ts.map +1 -0
  189. package/dist/tools/mailbox-organization.js +525 -0
  190. package/dist/tools/mailbox-organization.js.map +1 -0
  191. package/dist/tools/notes.d.ts +70 -0
  192. package/dist/tools/notes.d.ts.map +1 -0
  193. package/dist/tools/notes.js +132 -0
  194. package/dist/tools/notes.js.map +1 -0
  195. package/dist/tools/tasks.d.ts +70 -0
  196. package/dist/tools/tasks.d.ts.map +1 -0
  197. package/dist/tools/tasks.js +122 -0
  198. package/dist/tools/tasks.js.map +1 -0
  199. package/dist/types/calendar.d.ts +56 -0
  200. package/dist/types/calendar.d.ts.map +1 -0
  201. package/dist/types/calendar.js +14 -0
  202. package/dist/types/calendar.js.map +1 -0
  203. package/dist/types/contacts.d.ts +92 -0
  204. package/dist/types/contacts.d.ts.map +1 -0
  205. package/dist/types/contacts.js +37 -0
  206. package/dist/types/contacts.js.map +1 -0
  207. package/dist/types/index.d.ts +11 -0
  208. package/dist/types/index.d.ts.map +1 -0
  209. package/dist/types/index.js +12 -0
  210. package/dist/types/index.js.map +1 -0
  211. package/dist/types/mail.d.ts +87 -0
  212. package/dist/types/mail.d.ts.map +1 -0
  213. package/dist/types/mail.js +32 -0
  214. package/dist/types/mail.js.map +1 -0
  215. package/dist/types/notes.d.ts +22 -0
  216. package/dist/types/notes.d.ts.map +1 -0
  217. package/dist/types/notes.js +5 -0
  218. package/dist/types/notes.js.map +1 -0
  219. package/dist/types/tasks.d.ts +27 -0
  220. package/dist/types/tasks.d.ts.map +1 -0
  221. package/dist/types/tasks.js +5 -0
  222. package/dist/types/tasks.js.map +1 -0
  223. package/dist/utils/dates.d.ts +62 -0
  224. package/dist/utils/dates.d.ts.map +1 -0
  225. package/dist/utils/dates.js +90 -0
  226. package/dist/utils/dates.js.map +1 -0
  227. package/dist/utils/errors.d.ts +198 -0
  228. package/dist/utils/errors.d.ts.map +1 -0
  229. package/dist/utils/errors.js +281 -0
  230. package/dist/utils/errors.js.map +1 -0
  231. package/dist/utils/index.d.ts +6 -0
  232. package/dist/utils/index.d.ts.map +1 -0
  233. package/dist/utils/index.js +6 -0
  234. package/dist/utils/index.js.map +1 -0
  235. package/package.json +75 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024
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 ADDED
@@ -0,0 +1,358 @@
1
+ # Outlook MCP Server
2
+
3
+ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides read-only access to Outlook for Mac. Access your emails, calendar events, contacts, tasks, and notes directly through MCP tools.
4
+
5
+ ## Features
6
+
7
+ - **Mostly read-only** - Calendar event creation supported; all other data is read-only
8
+ - **Two backends** - AppleScript for classic Outlook, Microsoft Graph API for new Outlook
9
+ - **Works offline** - AppleScript backend requires no network (Graph API requires internet)
10
+ - **Fast and reliable** - Direct communication with Outlook or Microsoft servers
11
+
12
+ ### Available Tools
13
+
14
+ **Accounts**
15
+ - `list_accounts` - List all configured Outlook accounts
16
+
17
+ **Mail**
18
+ - `list_folders` - List all mail folders with unread counts (supports `account_id` filtering)
19
+ - `list_emails` - List emails in a folder with pagination
20
+ - `search_emails` - Search emails by subject, sender, or content
21
+ - `get_email` - Get full email details including body
22
+ - `get_unread_count` - Get unread email count
23
+ - `send_email` - Send an email with attachments and HTML support (AppleScript backend only)
24
+
25
+ **Calendar**
26
+ - `list_calendars` - List all calendars
27
+ - `list_events` - List events with date range filtering
28
+ - `get_event` - Get event details
29
+ - `search_events` - Search events by title
30
+ - `create_event` - Create a new calendar event (AppleScript backend only)
31
+ - `respond_to_event` - Accept, decline, or tentatively accept event invitations (AppleScript backend only)
32
+ - `delete_event` - Delete a calendar event or recurring series (AppleScript backend only)
33
+ - `update_event` - Update event details (title, time, location, etc.) (AppleScript backend only)
34
+
35
+ **Contacts**
36
+ - `list_contacts` - List all contacts with pagination
37
+ - `search_contacts` - Search contacts by name
38
+ - `get_contact` - Get contact details
39
+
40
+ **Tasks**
41
+ - `list_tasks` - List tasks with completion filtering
42
+ - `get_task` - Get task details
43
+ - `search_tasks` - Search tasks by name
44
+
45
+ **Notes**
46
+ - `list_notes` - List all notes
47
+ - `get_note` - Get note details
48
+ - `search_notes` - Search notes by content
49
+
50
+ > **Note**: Notes are only supported with the AppleScript backend. Microsoft Graph API does not provide access to Outlook Notes.
51
+
52
+ ## Known Limitations
53
+
54
+ ### AppleScript Backend
55
+
56
+ **Google Accounts Not Supported**
57
+
58
+ Google accounts configured in Outlook for Mac cannot be accessed via the AppleScript backend. This is a macOS/Outlook limitation - Google accounts use a proprietary OAuth integration that isn't exposed through AppleScript.
59
+
60
+ **Supported account types:**
61
+ - Exchange accounts
62
+ - IMAP accounts
63
+ - POP accounts
64
+
65
+ **Not supported:**
66
+ - Google accounts (native integration)
67
+
68
+ **Workarounds:**
69
+ 1. Configure Google as an IMAP account instead of using the native Google integration
70
+ 2. Use the Graph API backend (`USE_GRAPH_API=1`) which has different account handling
71
+
72
+ **Write Operations**
73
+
74
+ Currently, write operations (event management, email sending) are only supported via the AppleScript backend. These features will be added to the Graph API backend in a future release:
75
+ - Event RSVP operations
76
+ - Event deletion
77
+ - Event updates
78
+ - Email sending
79
+
80
+ For these operations, use the AppleScript backend with classic Outlook for Mac.
81
+
82
+ ### Graph API Backend
83
+
84
+ **Notes Not Available**
85
+
86
+ Microsoft Graph API does not provide access to Outlook Notes. If you need access to notes, use the AppleScript backend.
87
+
88
+ ## Backends
89
+
90
+ ### AppleScript (Default)
91
+
92
+ The default backend uses AppleScript to communicate with Microsoft Outlook for Mac. This works best with classic Outlook and requires Outlook to be running.
93
+
94
+ ### Microsoft Graph API
95
+
96
+ For "new Outlook" for Mac (cloud-based), use the Microsoft Graph API backend. This connects directly to Microsoft's servers and doesn't require Outlook to be running.
97
+
98
+ To enable the Graph API backend, set the environment variable:
99
+
100
+ ```bash
101
+ USE_GRAPH_API=1
102
+ ```
103
+
104
+ #### First-Time Authentication
105
+
106
+ When using the Graph API backend for the first time, you'll need to authenticate:
107
+
108
+ 1. The server will display a device code and URL
109
+ 2. Visit https://microsoft.com/devicelogin
110
+ 3. Enter the code displayed in the terminal
111
+ 4. Sign in with your Microsoft account
112
+ 5. Grant the requested permissions
113
+
114
+ Your authentication tokens are stored securely in `~/.outlook-mcp/tokens.json` and will be refreshed automatically.
115
+
116
+ #### Required Permissions
117
+
118
+ The Graph API backend requests these Microsoft Graph permissions:
119
+ - `Mail.Read` - Read your mail
120
+ - `Calendars.Read` - Read your calendars (will require `Calendars.ReadWrite` when Graph API event creation is added)
121
+ - `Contacts.Read` - Read your contacts
122
+ - `Tasks.Read` - Read your tasks
123
+ - `User.Read` - Read your profile
124
+ - `offline_access` - Maintain access (for token refresh)
125
+
126
+ ## Installation
127
+
128
+ ### Using npx (recommended)
129
+
130
+ ```bash
131
+ npx -y @jbctechsolutions/mcp-outlook-mac
132
+ ```
133
+
134
+ ### Using npm
135
+
136
+ ```bash
137
+ npm install -g @jbctechsolutions/mcp-outlook-mac
138
+ ```
139
+
140
+ ## Configuration
141
+
142
+ ### Claude Desktop
143
+
144
+ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
145
+
146
+ **AppleScript backend (default):**
147
+ ```json
148
+ {
149
+ "mcpServers": {
150
+ "outlook-mac": {
151
+ "command": "npx",
152
+ "args": ["-y", "@jbctechsolutions/mcp-outlook-mac"]
153
+ }
154
+ }
155
+ }
156
+ ```
157
+
158
+ **Graph API backend (for new Outlook):**
159
+ ```json
160
+ {
161
+ "mcpServers": {
162
+ "outlook-mac": {
163
+ "command": "npx",
164
+ "args": ["-y", "@jbctechsolutions/mcp-outlook-mac"],
165
+ "env": {
166
+ "USE_GRAPH_API": "1"
167
+ }
168
+ }
169
+ }
170
+ }
171
+ ```
172
+
173
+ ### Claude Code
174
+
175
+ Add to your Claude Code MCP settings:
176
+
177
+ **AppleScript backend (default):**
178
+ ```json
179
+ {
180
+ "mcpServers": {
181
+ "outlook-mac": {
182
+ "command": "npx",
183
+ "args": ["-y", "@jbctechsolutions/mcp-outlook-mac"]
184
+ }
185
+ }
186
+ }
187
+ ```
188
+
189
+ **Graph API backend (for new Outlook):**
190
+ ```json
191
+ {
192
+ "mcpServers": {
193
+ "outlook-mac": {
194
+ "command": "npx",
195
+ "args": ["-y", "@jbctechsolutions/mcp-outlook-mac"],
196
+ "env": {
197
+ "USE_GRAPH_API": "1"
198
+ }
199
+ }
200
+ }
201
+ }
202
+ ```
203
+
204
+ ## Requirements
205
+
206
+ ### AppleScript Backend
207
+ - macOS
208
+ - Microsoft Outlook for Mac (must be running when using tools)
209
+ - Node.js 18 or later
210
+ - Automation permission for Outlook (you'll be prompted on first use)
211
+
212
+ ### Graph API Backend
213
+ - macOS, Windows, or Linux
214
+ - Microsoft account (personal or work/school)
215
+ - Node.js 18 or later
216
+ - Internet connection
217
+
218
+ ## Permissions
219
+
220
+ ### AppleScript Backend
221
+
222
+ The MCP server communicates with Outlook via AppleScript. On first use, you'll be prompted to grant automation permission. You can also configure this in:
223
+
224
+ **System Settings > Privacy & Security > Automation**
225
+
226
+ Make sure your terminal or Claude Desktop is allowed to control Microsoft Outlook.
227
+
228
+ ### Graph API Backend
229
+
230
+ The Graph API backend requires you to sign in with your Microsoft account and grant permissions to read your mail, calendar, contacts, and tasks. See the [First-Time Authentication](#first-time-authentication) section above.
231
+
232
+ ## Troubleshooting
233
+
234
+ ### AppleScript Backend
235
+
236
+ #### Outlook not running
237
+
238
+ The server requires Outlook to be running. Start Microsoft Outlook before using the MCP tools.
239
+
240
+ #### Permission denied
241
+
242
+ If you see an automation permission error:
243
+
244
+ 1. Open **System Settings > Privacy & Security > Automation**
245
+ 2. Find your terminal app or Claude Desktop
246
+ 3. Enable the toggle for Microsoft Outlook
247
+
248
+ #### Timeout errors
249
+
250
+ Large mailboxes may cause timeout errors. Try reducing the `limit` parameter in your queries.
251
+
252
+ ### Graph API Backend
253
+
254
+ #### Authentication required
255
+
256
+ If you see "Microsoft Graph authentication required", you need to complete the device code flow:
257
+
258
+ 1. Look for the device code in the terminal output
259
+ 2. Visit https://microsoft.com/devicelogin
260
+ 3. Enter the code and sign in
261
+
262
+ #### Rate limited
263
+
264
+ Microsoft Graph API has rate limits. If you see rate limit errors, wait a few moments before trying again.
265
+
266
+ #### Permission denied
267
+
268
+ If you see permission errors, you may need to re-authenticate or your admin may have restricted access. Sign out and sign in again:
269
+
270
+ ```bash
271
+ # Delete token cache to force re-authentication
272
+ rm ~/.outlook-mcp/tokens.json
273
+ ```
274
+
275
+ #### Notes not available
276
+
277
+ Outlook Notes are not supported by Microsoft Graph API. If you need access to notes, use the AppleScript backend instead.
278
+
279
+ ## How It Works
280
+
281
+ This MCP server supports two backends:
282
+
283
+ ### AppleScript Backend (Default)
284
+
285
+ Uses AppleScript to communicate with Microsoft Outlook for Mac:
286
+ - Works best with classic Outlook for Mac
287
+ - Requires Outlook to be running
288
+ - Works offline (no network required)
289
+ - Full support for Notes
290
+
291
+ ### Graph API Backend
292
+
293
+ Uses Microsoft Graph API to access your data:
294
+ - Works with "new Outlook" for Mac (cloud-based)
295
+ - Connects directly to Microsoft's servers
296
+ - Works without Outlook running
297
+ - Supports personal and work/school accounts
298
+ - Does not support Notes (Graph API limitation)
299
+
300
+ ## Environment Variables
301
+
302
+ | Variable | Description | Default |
303
+ |----------|-------------|---------|
304
+ | `USE_GRAPH_API` | Set to `1` or `true` to use Microsoft Graph API backend | (unset, uses AppleScript) |
305
+ | `OUTLOOK_MCP_CLIENT_ID` | Override the embedded Azure AD client ID | (embedded) |
306
+ | `OUTLOOK_MCP_TENANT_ID` | Azure AD tenant ID (`common` for multi-tenant) | `common` |
307
+
308
+ ## Development
309
+
310
+ ```bash
311
+ # Install dependencies
312
+ npm install
313
+
314
+ # Build
315
+ npm run build
316
+
317
+ # Run tests
318
+ npm test
319
+
320
+ # Run with coverage
321
+ npm run test:coverage
322
+
323
+ # Lint
324
+ npm run lint
325
+
326
+ # Type check
327
+ npm run typecheck
328
+ ```
329
+
330
+ ## Architecture
331
+
332
+ ```
333
+ src/
334
+ ├── applescript/ # AppleScript integration (default backend)
335
+ │ ├── executor.ts # osascript wrapper
336
+ │ ├── scripts.ts # AppleScript templates
337
+ │ ├── parser.ts # Output parsing
338
+ │ ├── repository.ts # IRepository implementation
339
+ │ └── content-readers.ts # Content reader implementations
340
+ ├── graph/ # Microsoft Graph API integration (optional backend)
341
+ │ ├── auth/ # Authentication (MSAL, device code flow)
342
+ │ │ ├── config.ts # Azure AD configuration
343
+ │ │ ├── token-cache.ts # Token persistence
344
+ │ │ └── device-code-flow.ts # Authentication flow
345
+ │ ├── client/ # Graph client wrapper
346
+ │ │ ├── graph-client.ts # API client
347
+ │ │ └── cache.ts # Response caching
348
+ │ ├── mappers/ # Graph type to row type mappers
349
+ │ ├── repository.ts # IRepository implementation
350
+ │ └── content-readers.ts # Content reader implementations
351
+ ├── tools/ # MCP tool implementations
352
+ ├── types/ # TypeScript type definitions
353
+ └── utils/ # Utilities (dates, errors, etc.)
354
+ ```
355
+
356
+ ## License
357
+
358
+ MIT
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Repository for Outlook account operations using AppleScript.
3
+ */
4
+ import { type AppleScriptAccountRow, type AppleScriptFolderWithAccountRow } from './parser.js';
5
+ export interface IAccountRepository {
6
+ /**
7
+ * Lists all Exchange accounts configured in Outlook.
8
+ */
9
+ listAccounts(): AppleScriptAccountRow[];
10
+ /**
11
+ * Gets the ID of the default account.
12
+ * Returns null if no default is set or no accounts exist.
13
+ */
14
+ getDefaultAccountId(): number | null;
15
+ /**
16
+ * Lists mail folders for specific accounts.
17
+ */
18
+ listMailFoldersByAccounts(accountIds: number[]): AppleScriptFolderWithAccountRow[];
19
+ }
20
+ export declare class AccountRepository implements IAccountRepository {
21
+ listAccounts(): AppleScriptAccountRow[];
22
+ getDefaultAccountId(): number | null;
23
+ listMailFoldersByAccounts(accountIds: number[]): AppleScriptFolderWithAccountRow[];
24
+ }
25
+ /**
26
+ * Creates an account repository instance.
27
+ */
28
+ export declare function createAccountRepository(): IAccountRepository;
29
+ //# sourceMappingURL=account-repository.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"account-repository.d.ts","sourceRoot":"","sources":["../../src/applescript/account-repository.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,+BAA+B,EACrC,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,YAAY,IAAI,qBAAqB,EAAE,CAAC;IAExC;;;OAGG;IACH,mBAAmB,IAAI,MAAM,GAAG,IAAI,CAAC;IAErC;;OAEG;IACH,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,+BAA+B,EAAE,CAAC;CACpF;AAMD,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D,YAAY,IAAI,qBAAqB,EAAE;IAKvC,mBAAmB,IAAI,MAAM,GAAG,IAAI;IAKpC,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,+BAA+B,EAAE;CAQnF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,kBAAkB,CAE5D"}
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Repository for Outlook account operations using AppleScript.
3
+ */
4
+ import { executeAppleScriptOrThrow } from './executor.js';
5
+ import { LIST_ACCOUNTS, GET_DEFAULT_ACCOUNT, listMailFoldersByAccounts } from './account-scripts.js';
6
+ import { parseAccounts, parseDefaultAccountId, parseFoldersWithAccount, } from './parser.js';
7
+ // =============================================================================
8
+ // Implementation
9
+ // =============================================================================
10
+ export class AccountRepository {
11
+ listAccounts() {
12
+ const output = executeAppleScriptOrThrow(LIST_ACCOUNTS);
13
+ return parseAccounts(output);
14
+ }
15
+ getDefaultAccountId() {
16
+ const output = executeAppleScriptOrThrow(GET_DEFAULT_ACCOUNT);
17
+ return parseDefaultAccountId(output);
18
+ }
19
+ listMailFoldersByAccounts(accountIds) {
20
+ if (accountIds.length === 0) {
21
+ return [];
22
+ }
23
+ const script = listMailFoldersByAccounts(accountIds);
24
+ const output = executeAppleScriptOrThrow(script);
25
+ return parseFoldersWithAccount(output);
26
+ }
27
+ }
28
+ /**
29
+ * Creates an account repository instance.
30
+ */
31
+ export function createAccountRepository() {
32
+ return new AccountRepository();
33
+ }
34
+ //# sourceMappingURL=account-repository.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"account-repository.js","sourceRoot":"","sources":["../../src/applescript/account-repository.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACrG,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,uBAAuB,GAGxB,MAAM,aAAa,CAAC;AAwBrB,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF,MAAM,OAAO,iBAAiB;IAC5B,YAAY;QACV,MAAM,MAAM,GAAG,yBAAyB,CAAC,aAAa,CAAC,CAAC;QACxD,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,mBAAmB;QACjB,MAAM,MAAM,GAAG,yBAAyB,CAAC,mBAAmB,CAAC,CAAC;QAC9D,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,yBAAyB,CAAC,UAAoB;QAC5C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,MAAM,GAAG,yBAAyB,CAAC,UAAU,CAAC,CAAC;QACrD,MAAM,MAAM,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;QACjD,OAAO,uBAAuB,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,IAAI,iBAAiB,EAAE,CAAC;AACjC,CAAC"}
@@ -0,0 +1,22 @@
1
+ /**
2
+ * AppleScript template strings for Outlook account operations.
3
+ *
4
+ * Outputs data in delimiter-based format for reliable parsing.
5
+ */
6
+ /**
7
+ * Lists all accounts in Outlook (Exchange, IMAP, POP).
8
+ * Returns: id, name, email address, type for each account
9
+ */
10
+ export declare const LIST_ACCOUNTS: string;
11
+ /**
12
+ * Gets the default account in Outlook.
13
+ * Returns: id of the default account, or first account if no default is set
14
+ */
15
+ export declare const GET_DEFAULT_ACCOUNT: string;
16
+ /**
17
+ * Lists mail folders for specific accounts (all types: Exchange, IMAP, POP).
18
+ *
19
+ * @param accountIds - Array of account IDs to query
20
+ */
21
+ export declare function listMailFoldersByAccounts(accountIds: number[]): string;
22
+ //# sourceMappingURL=account-scripts.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"account-scripts.d.ts","sourceRoot":"","sources":["../../src/applescript/account-scripts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH;;;GAGG;AACH,eAAO,MAAM,aAAa,QAgDzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QA8B/B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAyEtE"}
@@ -0,0 +1,176 @@
1
+ /**
2
+ * AppleScript template strings for Outlook account operations.
3
+ *
4
+ * Outputs data in delimiter-based format for reliable parsing.
5
+ */
6
+ import { DELIMITERS } from './scripts.js';
7
+ // =============================================================================
8
+ // Account Scripts
9
+ // =============================================================================
10
+ /**
11
+ * Lists all accounts in Outlook (Exchange, IMAP, POP).
12
+ * Returns: id, name, email address, type for each account
13
+ */
14
+ export const LIST_ACCOUNTS = `
15
+ tell application "Microsoft Outlook"
16
+ set output to ""
17
+
18
+ -- Get Exchange accounts
19
+ try
20
+ set exchangeAccounts to every exchange account
21
+ repeat with acc in exchangeAccounts
22
+ try
23
+ set accId to id of acc
24
+ set accName to name of acc
25
+ set accEmail to email address of acc
26
+ set accType to "exchange"
27
+ set output to output & "${DELIMITERS.RECORD}id${DELIMITERS.EQUALS}" & accId & "${DELIMITERS.FIELD}name${DELIMITERS.EQUALS}" & accName & "${DELIMITERS.FIELD}email${DELIMITERS.EQUALS}" & accEmail & "${DELIMITERS.FIELD}type${DELIMITERS.EQUALS}" & accType
28
+ end try
29
+ end repeat
30
+ end try
31
+
32
+ -- Get IMAP accounts
33
+ try
34
+ set imapAccounts to every imap account
35
+ repeat with acc in imapAccounts
36
+ try
37
+ set accId to id of acc
38
+ set accName to name of acc
39
+ set accEmail to email address of acc
40
+ set accType to "imap"
41
+ set output to output & "${DELIMITERS.RECORD}id${DELIMITERS.EQUALS}" & accId & "${DELIMITERS.FIELD}name${DELIMITERS.EQUALS}" & accName & "${DELIMITERS.FIELD}email${DELIMITERS.EQUALS}" & accEmail & "${DELIMITERS.FIELD}type${DELIMITERS.EQUALS}" & accType
42
+ end try
43
+ end repeat
44
+ end try
45
+
46
+ -- Get POP accounts
47
+ try
48
+ set popAccounts to every pop account
49
+ repeat with acc in popAccounts
50
+ try
51
+ set accId to id of acc
52
+ set accName to name of acc
53
+ set accEmail to email address of acc
54
+ set accType to "pop"
55
+ set output to output & "${DELIMITERS.RECORD}id${DELIMITERS.EQUALS}" & accId & "${DELIMITERS.FIELD}name${DELIMITERS.EQUALS}" & accName & "${DELIMITERS.FIELD}email${DELIMITERS.EQUALS}" & accEmail & "${DELIMITERS.FIELD}type${DELIMITERS.EQUALS}" & accType
56
+ end try
57
+ end repeat
58
+ end try
59
+
60
+ return output
61
+ end tell
62
+ `;
63
+ /**
64
+ * Gets the default account in Outlook.
65
+ * Returns: id of the default account, or first account if no default is set
66
+ */
67
+ export const GET_DEFAULT_ACCOUNT = `
68
+ tell application "Microsoft Outlook"
69
+ try
70
+ -- Try to get the default account
71
+ set defaultAcc to default account
72
+ set accId to id of defaultAcc
73
+ return "id${DELIMITERS.EQUALS}" & accId
74
+ on error
75
+ -- Fallback: return first available account (try exchange, then imap, then pop)
76
+ try
77
+ set firstAcc to first exchange account
78
+ set accId to id of firstAcc
79
+ return "id${DELIMITERS.EQUALS}" & accId
80
+ on error
81
+ try
82
+ set firstAcc to first imap account
83
+ set accId to id of firstAcc
84
+ return "id${DELIMITERS.EQUALS}" & accId
85
+ on error
86
+ try
87
+ set firstAcc to first pop account
88
+ set accId to id of firstAcc
89
+ return "id${DELIMITERS.EQUALS}" & accId
90
+ on error
91
+ return "error${DELIMITERS.EQUALS}No accounts found"
92
+ end try
93
+ end try
94
+ end try
95
+ end try
96
+ end tell
97
+ `;
98
+ /**
99
+ * Lists mail folders for specific accounts (all types: Exchange, IMAP, POP).
100
+ *
101
+ * @param accountIds - Array of account IDs to query
102
+ */
103
+ export function listMailFoldersByAccounts(accountIds) {
104
+ const accountFilter = accountIds.map(id => `id ${id}`).join(' or id ');
105
+ return `
106
+ tell application "Microsoft Outlook"
107
+ set output to ""
108
+
109
+ -- Get folders from Exchange accounts
110
+ try
111
+ set targetAccounts to (every exchange account whose ${accountFilter})
112
+ repeat with acc in targetAccounts
113
+ set accId to id of acc
114
+ set allFolders to mail folders of acc
115
+ repeat with f in allFolders
116
+ try
117
+ set fId to id of f
118
+ set fName to name of f
119
+ set uCount to unread count of f
120
+ set mCount to 0
121
+ try
122
+ set mCount to count of messages of f
123
+ end try
124
+ set output to output & "${DELIMITERS.RECORD}id${DELIMITERS.EQUALS}" & fId & "${DELIMITERS.FIELD}name${DELIMITERS.EQUALS}" & fName & "${DELIMITERS.FIELD}unreadCount${DELIMITERS.EQUALS}" & uCount & "${DELIMITERS.FIELD}messageCount${DELIMITERS.EQUALS}" & mCount & "${DELIMITERS.FIELD}accountId${DELIMITERS.EQUALS}" & accId
125
+ end try
126
+ end repeat
127
+ end repeat
128
+ end try
129
+
130
+ -- Get folders from IMAP accounts
131
+ try
132
+ set targetAccounts to (every imap account whose ${accountFilter})
133
+ repeat with acc in targetAccounts
134
+ set accId to id of acc
135
+ set allFolders to mail folders of acc
136
+ repeat with f in allFolders
137
+ try
138
+ set fId to id of f
139
+ set fName to name of f
140
+ set uCount to unread count of f
141
+ set mCount to 0
142
+ try
143
+ set mCount to count of messages of f
144
+ end try
145
+ set output to output & "${DELIMITERS.RECORD}id${DELIMITERS.EQUALS}" & fId & "${DELIMITERS.FIELD}name${DELIMITERS.EQUALS}" & fName & "${DELIMITERS.FIELD}unreadCount${DELIMITERS.EQUALS}" & uCount & "${DELIMITERS.FIELD}messageCount${DELIMITERS.EQUALS}" & mCount & "${DELIMITERS.FIELD}accountId${DELIMITERS.EQUALS}" & accId
146
+ end try
147
+ end repeat
148
+ end repeat
149
+ end try
150
+
151
+ -- Get folders from POP accounts
152
+ try
153
+ set targetAccounts to (every pop account whose ${accountFilter})
154
+ repeat with acc in targetAccounts
155
+ set accId to id of acc
156
+ set allFolders to mail folders of acc
157
+ repeat with f in allFolders
158
+ try
159
+ set fId to id of f
160
+ set fName to name of f
161
+ set uCount to unread count of f
162
+ set mCount to 0
163
+ try
164
+ set mCount to count of messages of f
165
+ end try
166
+ set output to output & "${DELIMITERS.RECORD}id${DELIMITERS.EQUALS}" & fId & "${DELIMITERS.FIELD}name${DELIMITERS.EQUALS}" & fName & "${DELIMITERS.FIELD}unreadCount${DELIMITERS.EQUALS}" & uCount & "${DELIMITERS.FIELD}messageCount${DELIMITERS.EQUALS}" & mCount & "${DELIMITERS.FIELD}accountId${DELIMITERS.EQUALS}" & accId
167
+ end try
168
+ end repeat
169
+ end repeat
170
+ end try
171
+
172
+ return output
173
+ end tell
174
+ `;
175
+ }
176
+ //# sourceMappingURL=account-scripts.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"account-scripts.js","sourceRoot":"","sources":["../../src/applescript/account-scripts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;kCAaK,UAAU,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,gBAAgB,UAAU,CAAC,KAAK,OAAO,UAAU,CAAC,MAAM,kBAAkB,UAAU,CAAC,KAAK,QAAQ,UAAU,CAAC,MAAM,mBAAmB,UAAU,CAAC,KAAK,OAAO,UAAU,CAAC,MAAM;;;;;;;;;;;;;;kCAcrN,UAAU,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,gBAAgB,UAAU,CAAC,KAAK,OAAO,UAAU,CAAC,MAAM,kBAAkB,UAAU,CAAC,KAAK,QAAQ,UAAU,CAAC,MAAM,mBAAmB,UAAU,CAAC,KAAK,OAAO,UAAU,CAAC,MAAM;;;;;;;;;;;;;;kCAcrN,UAAU,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,gBAAgB,UAAU,CAAC,KAAK,OAAO,UAAU,CAAC,MAAM,kBAAkB,UAAU,CAAC,KAAK,QAAQ,UAAU,CAAC,MAAM,mBAAmB,UAAU,CAAC,KAAK,OAAO,UAAU,CAAC,MAAM;;;;;;;CAOtP,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;gBAMnB,UAAU,CAAC,MAAM;;;;;;kBAMf,UAAU,CAAC,MAAM;;;;;oBAKf,UAAU,CAAC,MAAM;;;;;sBAKf,UAAU,CAAC,MAAM;;yBAEd,UAAU,CAAC,MAAM;;;;;;CAMzC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,UAAoB;IAC5D,MAAM,aAAa,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEvE,OAAO;;;;;;0DAMiD,aAAa;;;;;;;;;;;;;oCAanC,UAAU,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,cAAc,UAAU,CAAC,KAAK,OAAO,UAAU,CAAC,MAAM,gBAAgB,UAAU,CAAC,KAAK,cAAc,UAAU,CAAC,MAAM,iBAAiB,UAAU,CAAC,KAAK,eAAe,UAAU,CAAC,MAAM,iBAAiB,UAAU,CAAC,KAAK,YAAY,UAAU,CAAC,MAAM;;;;;;;;sDAQzQ,aAAa;;;;;;;;;;;;;oCAa/B,UAAU,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,cAAc,UAAU,CAAC,KAAK,OAAO,UAAU,CAAC,MAAM,gBAAgB,UAAU,CAAC,KAAK,cAAc,UAAU,CAAC,MAAM,iBAAiB,UAAU,CAAC,KAAK,eAAe,UAAU,CAAC,MAAM,iBAAiB,UAAU,CAAC,KAAK,YAAY,UAAU,CAAC,MAAM;;;;;;;;qDAQ1Q,aAAa;;;;;;;;;;;;;oCAa9B,UAAU,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,cAAc,UAAU,CAAC,KAAK,OAAO,UAAU,CAAC,MAAM,gBAAgB,UAAU,CAAC,KAAK,cAAc,UAAU,CAAC,MAAM,iBAAiB,UAAU,CAAC,KAAK,eAAe,UAAU,CAAC,MAAM,iBAAiB,UAAU,CAAC,KAAK,YAAY,UAAU,CAAC,MAAM;;;;;;;;CAQ9T,CAAC;AACF,CAAC"}