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