msteams-mcp 0.27.0 → 0.27.1
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.
- package/README.md +129 -76
- package/dist/cli.js +0 -0
- package/dist/index.js +0 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,24 +1,31 @@
|
|
|
1
|
-
# Teams MCP Server & CLI
|
|
1
|
+
# Microsoft Teams MCP Server & CLI
|
|
2
2
|
|
|
3
|
-
[
|
|
4
|
-
[
|
|
5
|
-
[
|
|
3
|
+
[CI](https://github.com/m0nkmaster/msteams-mcp/actions/workflows/ci.yml)
|
|
4
|
+
[npm version](https://www.npmjs.com/package/msteams-mcp)
|
|
5
|
+
[npm downloads](https://www.npmjs.com/package/msteams-mcp)
|
|
6
|
+
[License: MIT](https://opensource.org/licenses/MIT)
|
|
7
|
+
[Node.js](https://nodejs.org/)
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
Give AI access to Microsoft Teams with your standard Teams login.
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
> [!IMPORTANT]
|
|
12
|
+
>
|
|
13
|
+
> ## No Azure setup, app registration, Graph permissions or IT support required.
|
|
10
14
|
|
|
11
|
-
|
|
15
|
+
Search messages and email, catch up on unread chats, read threads, send replies, retrieve meeting transcripts and more.
|
|
12
16
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
17
|
+
## Why msteams-mcp?
|
|
18
|
+
|
|
19
|
+
- **Do real work** - search, unread chats, threads, replies, people, channels, meetings, transcripts, files, reactions and more.
|
|
20
|
+
- **Sign in once** - tokens refresh automatically and the browser stays out of routine operations.
|
|
21
|
+
- **Secure** - the assistant has only your existing Teams permissions, with encrypted session data stored locally.
|
|
22
|
+
- **Use it anywhere** - every capability works through both MCP clients and the included `msteams` CLI.
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
## Quick start
|
|
18
27
|
|
|
19
|
-
**Security:** Uses the same authentication as the Teams web client - your access is limited to what your account can already do.
|
|
20
28
|
|
|
21
|
-
## Installation
|
|
22
29
|
|
|
23
30
|
### Prerequisites
|
|
24
31
|
|
|
@@ -26,7 +33,9 @@ This server calls Microsoft's Teams APIs directly (Substrate, chatsvc, CSA) - t
|
|
|
26
33
|
- A Microsoft account with Teams access
|
|
27
34
|
- Google Chrome, Microsoft Edge, or Chromium browser installed
|
|
28
35
|
|
|
29
|
-
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
### Configure your MCP client
|
|
30
39
|
|
|
31
40
|
Add to your MCP client configuration (e.g., Claude Desktop, Windsurf, Cursor):
|
|
32
41
|
|
|
@@ -41,7 +50,18 @@ Add to your MCP client configuration (e.g., Claude Desktop, Windsurf, Cursor):
|
|
|
41
50
|
}
|
|
42
51
|
```
|
|
43
52
|
|
|
44
|
-
That
|
|
53
|
+
That is it. `npx` downloads and runs the latest version. Ask your assistant to call `teams_login` once, complete the normal Microsoft sign-in in the browser, and then start using Teams.
|
|
54
|
+
|
|
55
|
+
## How it works
|
|
56
|
+
|
|
57
|
+
This server calls Microsoft's Teams services directly (Substrate, chatsvc, CSA), using the authenticated session created by the Teams web app.
|
|
58
|
+
|
|
59
|
+
1. `teams_login` opens a browser for your normal Microsoft sign-in.
|
|
60
|
+
2. The resulting OAuth tokens and session data are encrypted and cached locally.
|
|
61
|
+
3. Routine operations use those tokens directly, without browser automation.
|
|
62
|
+
4. Expiring tokens are refreshed automatically over HTTP, with headless browser SSO as a fallback.
|
|
63
|
+
|
|
64
|
+
Your access remains limited to what your Teams account can already see and do.
|
|
45
65
|
|
|
46
66
|
### From Source (alternative)
|
|
47
67
|
|
|
@@ -68,9 +88,9 @@ Then configure your MCP client:
|
|
|
68
88
|
|
|
69
89
|
The server uses your system's Chrome (macOS/Linux) or Edge (Windows) for authentication.
|
|
70
90
|
|
|
71
|
-
### CLI
|
|
91
|
+
### CLI
|
|
72
92
|
|
|
73
|
-
The same functionality is also available as a standalone command-line tool, `msteams`. This is useful when you want Teams from a shell or script instead of an MCP client
|
|
93
|
+
The same functionality is also available as a standalone command-line tool, `msteams`. This is useful when you want Teams from a shell or script instead of an MCP client.
|
|
74
94
|
|
|
75
95
|
Install it globally from npm:
|
|
76
96
|
|
|
@@ -78,7 +98,7 @@ Install it globally from npm:
|
|
|
78
98
|
npm install -g msteams-mcp
|
|
79
99
|
```
|
|
80
100
|
|
|
81
|
-
This installs two binaries: `msteams-mcp` (the MCP server) and `msteams` (the CLI). Or run it without installing:
|
|
101
|
+
This installs two binaries: `msteams-mcp` (the MCP server) and `msteams` (the CLI wrapper). Or run it without installing:
|
|
82
102
|
|
|
83
103
|
```bash
|
|
84
104
|
npx -y msteams-mcp msteams status
|
|
@@ -88,86 +108,115 @@ See [CLI Usage](#cli-usage) for commands.
|
|
|
88
108
|
|
|
89
109
|
## Available Tools
|
|
90
110
|
|
|
111
|
+
|
|
112
|
+
|
|
91
113
|
### Search & Discovery
|
|
92
114
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
115
|
+
|
|
116
|
+
| Tool | Description |
|
|
117
|
+
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
118
|
+
| `teams_search` | Search Teams messages with operators (`from:`, `sent:`, `in:`, `hasattachment:`, etc.) |
|
|
119
|
+
| `teams_search_email` | Search emails in your mailbox (same auth as Teams - no extra login) |
|
|
120
|
+
| `teams_list_chats` | List recent conversations (1:1, group, meeting, channel) with a last-message preview |
|
|
121
|
+
| `teams_get_message` | Get a single message by ID with full content (any age); includes reactions |
|
|
122
|
+
| `teams_get_thread` | Get messages from a conversation/thread; includes reactions; `threadRootId` scopes to one channel thread; `fromUrl` accepts a Teams message deep link |
|
|
123
|
+
| `teams_find_channel` | Find channels by name (your teams + org-wide discovery) |
|
|
124
|
+
| `teams_get_tags` | List a team's channel tags for tag @mentions |
|
|
125
|
+
| `teams_get_activity` | Get activity feed (mentions, reactions, replies, notifications) |
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
|
|
102
129
|
|
|
103
130
|
### Messaging
|
|
104
131
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
132
|
+
|
|
133
|
+
| Tool | Description |
|
|
134
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
135
|
+
| `teams_send_message` | Send a message (default: self-chat/notes). `replyToMessageId` for thread replies, `subject` for a new channel thread, `scheduleAt` to schedule, `contentType` (`auto`/`text`/`html`/`markdown`) to control formatting |
|
|
136
|
+
| `teams_wait_for_reply` | Block until a new message arrives (server-side poll, capped ~110s); idempotent `after`/`nextAfter` cursor - pair with `teams_send_message` |
|
|
137
|
+
| `teams_edit_message` | Edit one of your own messages (`contentType` supported) |
|
|
138
|
+
| `teams_delete_message` | Delete one of your own messages (soft delete) |
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
|
|
111
142
|
|
|
112
143
|
### People & Contacts
|
|
113
144
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
145
|
+
|
|
146
|
+
| Tool | Description |
|
|
147
|
+
| ----------------------------- | ------------------------------------------------------------------------------ |
|
|
148
|
+
| `teams_get_me` | Get current user profile (email, name, ID) |
|
|
149
|
+
| `teams_search_people` | Search for people by name or email |
|
|
150
|
+
| `teams_get_frequent_contacts` | Get frequently contacted people (useful for name resolution) |
|
|
151
|
+
| `teams_get_person` | Resolve one or more MRIs to full profiles (name, email, job title, department) |
|
|
152
|
+
| `teams_get_chat` | Get conversation ID for 1:1 chat with a person |
|
|
153
|
+
| `teams_create_group_chat` | Create a new group chat with multiple people (2+ others) |
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
|
|
122
157
|
|
|
123
158
|
### Organisation
|
|
124
159
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
160
|
+
|
|
161
|
+
| Tool | Description |
|
|
162
|
+
| ---------------------------- | ------------------------------------------------------------ |
|
|
163
|
+
| `teams_get_favorites` | Get pinned/favourite conversations |
|
|
164
|
+
| `teams_add_favorite` | Pin a conversation |
|
|
165
|
+
| `teams_remove_favorite` | Unpin a conversation |
|
|
166
|
+
| `teams_save_message` | Bookmark a message |
|
|
167
|
+
| `teams_unsave_message` | Remove bookmark from a message |
|
|
168
|
+
| `teams_get_saved_messages` | Get list of saved/bookmarked messages with source references |
|
|
169
|
+
| `teams_get_followed_threads` | Get list of followed threads with source references |
|
|
170
|
+
| `teams_get_unread` | Get unread counts (aggregate or per-conversation) |
|
|
171
|
+
| `teams_mark_read` | Mark a conversation as read up to a message |
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
|
|
136
175
|
|
|
137
176
|
### Reactions
|
|
138
177
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
178
|
+
|
|
179
|
+
| Tool | Description |
|
|
180
|
+
| ----------------------- | -------------------------------------------------------- |
|
|
181
|
+
| `teams_search_emoji` | Search for emojis by name (standard + custom org emojis) |
|
|
182
|
+
| `teams_add_reaction` | Add an emoji reaction to a message |
|
|
183
|
+
| `teams_remove_reaction` | Remove an emoji reaction from a message |
|
|
184
|
+
|
|
144
185
|
|
|
145
186
|
**Quick reactions:** `like`, `heart`, `laugh`, `surprised`, `sad`, `angry` can be used directly without searching.
|
|
146
187
|
|
|
147
188
|
### Calendar & Meetings
|
|
148
189
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
|
190
|
+
|
|
191
|
+
| Tool | Description |
|
|
192
|
+
| ---------------------- | ---------------------------------------------------------------------- |
|
|
193
|
+
| `teams_get_meetings` | Get meetings from calendar (defaults to next 7 days) |
|
|
152
194
|
| `teams_get_transcript` | Get meeting transcript (requires `threadId` from `teams_get_meetings`) |
|
|
153
195
|
|
|
196
|
+
|
|
154
197
|
`teams_get_meetings` returns: subject, times, organiser, join URL, `threadId` for meeting chat. Use `threadId` with `teams_get_thread` to read meeting chat, or with `teams_get_transcript` to get the full transcript with speakers and timestamps.
|
|
155
198
|
|
|
156
199
|
### Files
|
|
157
200
|
|
|
158
|
-
|
|
159
|
-
|
|
201
|
+
|
|
202
|
+
| Tool | Description |
|
|
203
|
+
| ------------------------ | ------------------------------------------------------------------ |
|
|
160
204
|
| `teams_get_shared_files` | Get files and links shared in a conversation (supports pagination) |
|
|
161
205
|
|
|
206
|
+
|
|
162
207
|
Returns both files (name, extension, URL, size) and links (URL, title), along with who shared each item. Works for channels, group chats, 1:1 chats, and meeting chats.
|
|
163
208
|
|
|
164
209
|
### Session
|
|
165
210
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
|
211
|
+
|
|
212
|
+
| Tool | Description |
|
|
213
|
+
| -------------- | -------------------------------------- |
|
|
214
|
+
| `teams_login` | Trigger manual login (opens browser) |
|
|
169
215
|
| `teams_status` | Check authentication and session state |
|
|
170
216
|
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
|
|
171
220
|
### Search Operators
|
|
172
221
|
|
|
173
222
|
Both `teams_search` (Teams messages) and `teams_search_email` (emails) support native operators:
|
|
@@ -192,11 +241,15 @@ Combine operators: `from:sarah@co.com sent:>=2026-01-18 hasattachment:true`
|
|
|
192
241
|
|
|
193
242
|
The server also exposes passive resources for context discovery:
|
|
194
243
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
|
198
|
-
| `teams://me/
|
|
199
|
-
| `teams://
|
|
244
|
+
|
|
245
|
+
| Resource URI | Description |
|
|
246
|
+
| ---------------------- | ---------------------- |
|
|
247
|
+
| `teams://me/profile` | Current user's profile |
|
|
248
|
+
| `teams://me/favorites` | Pinned conversations |
|
|
249
|
+
| `teams://status` | Authentication status |
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
|
|
200
253
|
|
|
201
254
|
## CLI Usage
|
|
202
255
|
|
|
@@ -253,13 +306,16 @@ npm run cli -- status
|
|
|
253
306
|
npm run cli -- send "Hi" --to "conversation-id"
|
|
254
307
|
```
|
|
255
308
|
|
|
309
|
+
|
|
310
|
+
|
|
256
311
|
## Limitations
|
|
257
312
|
|
|
258
313
|
- **Login required** - Run `teams_login` to authenticate (opens browser)
|
|
259
314
|
- **Token expiry** - Tokens expire after ~1 hour; headless refresh is attempted or run `teams_login` again when needed
|
|
260
315
|
- **Undocumented APIs** - Uses Microsoft's internal APIs which may change without notice
|
|
261
|
-
- **Search limitations** - Full-text search only; thread replies not matching search terms won't appear (use `teams_get_thread` for full context)
|
|
262
|
-
|
|
316
|
+
- **Search limitations** - Full-text search only; thread replies not matching search terms won't appear (but LLM will likely use `teams_get_thread` for full context)
|
|
317
|
+
|
|
318
|
+
|
|
263
319
|
|
|
264
320
|
## Session Files
|
|
265
321
|
|
|
@@ -310,6 +366,3 @@ See [AGENTS.md](AGENTS.md) for detailed architecture and contribution guidelines
|
|
|
310
366
|
|
|
311
367
|
---
|
|
312
368
|
|
|
313
|
-
## Teams Chat Export Bookmarklet
|
|
314
|
-
|
|
315
|
-
This repo also includes a standalone bookmarklet for exporting Teams chat messages to Markdown. See [teams-bookmarklet/README.md](teams-bookmarklet/README.md).
|
package/dist/cli.js
CHANGED
|
File without changes
|
package/dist/index.js
CHANGED
|
File without changes
|