teams MCP server
Commit Nov 14, 2026Connects MCP clients to Microsoft Teams to discover channels, read messages, and send chats via Microsoft Graph.
Also known as ralscha/teams-mcp
- Stars
- 0
- Tools
- 25
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is teams MCP?
teams connects MCP clients to Microsoft Teams to discover channels, read messages, and send chats via Microsoft Graph. It exposes 25 tools, such as teams_get_current_user, teams_get_user, teams_list_users.
Summary generated from the project's README
About teams MCP server
Accessing Microsoft Teams data through an AI client is possible with this MCP server, which connects to Microsoft Graph to manage communications. Developers can use it to discover teams, channels, and chats, or to read and search through messages. It supports both stdio and streamable HTTP transports, making it compatible with local desktop clients or remote setups.
The server operates in two distinct modes. By default, it runs in a safe readonly mode that allows users to list members, get channel messages, and search text. When the TEAMS_MODE environment variable is set to readwrite, the server enables additional tools to create chats, send channel messages, and edit or delete existing communications.
Authentication is handled via several methods, including device-code OAuth, client credentials, or an existing access token. For most users, the device-code method is recommended as it allows the server to act with delegated user permissions, which is necessary for sending messages. The server can be configured with a Microsoft Entra application ID and tenant ID to establish a secure connection.
What you can do with it
- 1Automate chat responsesEnable the AI to send new messages or replies to existing threads in a chat or channel.
Written from the project's README. Every use case is checked against a quote from it.
teams MCP tools 25
Detected from the READMEteams_get_current_userteams_get_userteams_list_usersteams_list_joined_teamsteams_list_channelsteams_get_channelteams_list_team_membersteams_get_channel_messageteams_get_channel_message_replyteams_list_channel_messagesteams_list_channel_message_repliesteams_list_chats
Show all 25 toolsShow fewer tools
teams_get_chatteams_list_chat_membersteams_search_messagesteams_get_chat_messageteams_list_chat_messagesteams_create_chatteams_send_channel_messageteams_update_channel_messageteams_delete_channel_messageteams_reply_to_channel_messageteams_send_chat_messageteams_update_chat_messageteams_delete_chat_message
Configuration
TEAMS_ACCESS_TOKENTEAMS_CLIENT_IDTEAMS_MODETEAMS_TENANT_ID
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableralscha/teams-mcp is public and reachablegithub.com/ralscha/teams-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/ralscha/teams-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model25 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubteams-mcp
A Model Context Protocol server that
connects MCP clients to Microsoft Teams through
Microsoft Graph.
It follows the same small Go project shape as jira-mcp and uses the official
github.com/modelcontextprotocol/go-sdk.
The server supports stdio and streamable HTTP, defaults to a safe readonly mode, and can authenticate with delegated device-code OAuth, client credentials, or an existing Graph access token.
The scope is intentionally focused: it discovers teams, channels, and chats; reads their messages; and, when explicitly enabled, sends messages. It is not intended to expose every Microsoft Teams or Microsoft Graph operation.
Installation
Download the latest release for your platform from this repository's
Releases page. Release archives contain the binary, README, and license;
checksums.txt and a GitHub artifact attestation are published alongside
them. You can also build from source:
go build ./cmd/teams-mcp
Confirm which build is installed with teams-mcp --version.
Tools
Read tools are always available:
| Tool | Description |
|---|---|
teams_get_current_user |
Get the Microsoft 365 user whose Teams data is being accessed |
teams_get_user |
Get one Microsoft 365 user by object id or UPN |
teams_list_users |
List Microsoft 365 users with optional prefix filtering |
teams_list_joined_teams |
List teams the user directly belongs to |
teams_list_channels |
List channels in a team |
teams_get_channel |
Get one channel by id |
teams_list_team_members |
List members in a team |
teams_get_channel_message |
Get a specific root channel message by id |
teams_get_channel_message_reply |
Get one reply by its id and root message id |
teams_list_channel_messages |
List root messages in a channel |
teams_list_channel_message_replies |
List replies to a root channel message |
teams_list_chats |
List one-on-one, group, and meeting chats, including participant summaries when available |
teams_get_chat |
Get one chat by id |
teams_list_chat_members |
List members in a chat |
teams_search_messages |
Search channel and chat messages by free text |
teams_get_chat_message |
Get a specific chat message by id |
teams_list_chat_messages |
List messages in a chat |
Write tools are exposed only with TEAMS_MODE=readwrite:
| Tool | Description |
|---|---|
teams_create_chat |
Create a one-on-one or group chat |
teams_send_channel_message |
Send a root channel message |
teams_update_channel_message |
Edit an existing root channel message |
teams_delete_channel_message |
Soft-delete an existing root channel message |
teams_reply_to_channel_message |
Reply to a root channel message |
teams_send_chat_message |
Send a message to an existing chat |
teams_update_chat_message |
Edit an existing chat message |
teams_delete_chat_message |
Soft-delete an existing chat message |
When a message includes mentions, read tools return a structured mentions
array with mentioned identity details. Write tools accept an optional
mentions array; when provided, set content_type to html and include
matching <at id="N">...</at> tags in message HTML.
For teams_create_chat, supply the other participants' Entra member user IDs;
the signed-in user is added automatically. A one-on-one chat takes exactly one
other user. Participants are assigned the owner role; in-tenant guest users
requiring the guest role are not supported by this tool. See Microsoft's
chat creation requirements.
Message search requires delegated authentication and searches the signed-in user's messages. Results include Graph's search snippet when available.
Paginated collection tools return Graph's opaque next_link when another
page exists. Pass it back unchanged on the next call. Message bodies are
returned in the text or html form supplied by Teams. Treat message HTML as
untrusted content and sanitize it before rendering it outside an MCP client.
The client honors Graph's Retry-After header. Delays over 30 seconds are
returned as tool errors with the requested delay instead of being retried
early. Transient gateway errors are retried for reads and searches; writes
are retried only when Graph explicitly rejects them with a throttling response.
See Microsoft's throttling guidance.
Recommended authentication: device code
Device-code OAuth signs in a work or school user and caches the refresh token outside the repository. It is the recommended method because normal Graph message sends require delegated user permissions.
1. Register a Microsoft Entra application
- In the Microsoft Entra admin center, create an app registration.
- Under Authentication, enable Allow public client flows.
- Add these delegated Microsoft Graph permissions for readonly mode:
User.Read,User.ReadBasic.All,Team.ReadBasic.All,TeamMember.Read.All,Channel.ReadBasic.All,ChannelMessage.Read.All,Chat.Read, andChatMember.Read. - For readwrite mode also add
ChannelMessage.Send,ChannelMessage.ReadWrite,ChatMessage.Send,Chat.ReadWrite, andChat.Create. Editing and soft-deleting messages requires theReadWritescopes; sending alone is not sufficient. - Grant tenant admin consent where your tenant requires it. In particular,
ChannelMessage.Read.Allrequires admin consent.
Microsoft documents the relevant permissions on the joined teams, channel list, channel message list, chat list, and chat message list API pages.
2. Run the server
export TEAMS_TENANT_ID=00000000-0000-0000-0000-000000000000
export TEAMS_CLIENT_ID=11111111-1111-1111-1111-111111111111
go run ./cmd/teams-mcp --mode=readonly --transport=stdio
On the first run, teams-mcp writes a Microsoft sign-in URL and user code to
stderr. Complete that sign-in once. The token is cached at the operating
system's user cache location (for example
~/.cache/teams-mcp/token.json on Linux). Set TEAMS_TOKEN_CACHE to choose a
different path, or pass --teams-token-cache= to disable persistence.
The cache contains Microsoft OAuth tokens. Do not commit, sync, or share it,
and keep its directory accessible only to the account running teams-mcp.
The default delegated scopes depend on the mode. Set TEAMS_SCOPES only when
you need to override them.
Cached tokens are isolated by tenant, application, authority, Graph base URL, and scopes. Caches written by older versions without cloud metadata require one new sign-in. Reordering the same scopes does not require another sign-in.
Other authentication methods
Existing access token
Set TEAMS_ACCESS_TOKEN or --teams-access-token. Auto-detection selects the
access-token method when a token is present. The server cannot refresh a
token supplied this way.
TEAMS_ACCESS_TOKEN=ey... teams-mcp --mode=readonly
For readwrite mode, the token must be delegated and include
ChannelMessage.Send and/or ChatMessage.Send. Microsoft Graph only supports
ordinary channel sends
and chat sends
with delegated permissions; its documented app-only permission is intended for
migration.
Client credentials (app-only reads)
Set TEAMS_TENANT_ID, TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET, and
TEAMS_USER_ID. TEAMS_USER_ID can be an object ID or user principal name and
selects the user whose teams and chats are read.
Grant the application the Graph application permissions needed by the
tools you use, normally User.Read.All, Team.ReadBasic.All,
Channel.ReadBasic.All, ChannelMessage.Read.All, and Chat.Read.All, then
grant admin consent. Client-credentials auth is intentionally rejected in
readwrite mode because it cannot perform normal Teams message sends.
Configuration
Flags override environment variables. When TEAMS_AUTH_METHOD=auto, an access
token wins, then a client secret, otherwise device code is selected.
| Environment variable | CLI flag | Default | Description |
|---|---|---|---|
TEAMS_TENANT_ID |
--teams-tenant-id |
Entra tenant ID or verified domain | |
TEAMS_CLIENT_ID |
--teams-client-id |
Entra application/client ID | |
TEAMS_CLIENT_SECRET |
--teams-client-secret |
Secret for client-credentials auth | |
TEAMS_ACCESS_TOKEN |
--teams-access-token |
Pre-acquired Graph token | |
TEAMS_USER_ID |
--teams-user-id |
Target object ID or UPN; required for app-only auth | |
TEAMS_AUTH_METHOD |
--auth-method |
auto |
auto, device-code, client-credentials, or access-token |
TEAMS_SCOPES |
--teams-scopes |
mode-dependent | Space- or comma-separated delegated scopes |
TEAMS_TOKEN_CACHE |
--teams-token-cache |
OS user cache | Device-code token cache path |
TEAMS_GRAPH_BASE_URL |
--teams-graph-base-url |
https://graph.microsoft.com/v1.0/ |
Graph API base, useful for national clouds |
TEAMS_AUTHORITY_URL |
--teams-authority-url |
https://login.microsoftonline.com/ |
Microsoft identity authority base |
TEAMS_MODE |
--mode |
readonly |
readonly or readwrite |
MCP_TRANSPORT |
--transport |
stdio |
stdio or http |
MCP_HTTP_ADDR |
--http-addr |
127.0.0.1:8080 |
HTTP listen address |
MCP client configuration
For Claude Desktop or another stdio host:
{
"mcpServers": {
"teams": {
"command": "teams-mcp",
"args": [],
"env": {
"TEAMS_TENANT_ID": "00000000-0000-0000-0000-000000000000",
"TEAMS_CLIENT_ID": "11111111-1111-1111-1111-111111111111",
"TEAMS_MODE": "readonly"
}
}
}
}
For VS Code, put the same server object under servers in .vscode/mcp.json.
It is usually easiest to run the binary once in a terminal to complete the
initial device-code sign-in before launching it from an MCP host.
Transports and security
The default stdio transport communicates over stdin/stdout:
teams-mcp --transport=stdio
Streamable HTTP listens on the configured address:
teams-mcp --transport=http --http-addr=127.0.0.1:8080
The HTTP transport defaults to loopback and rejects cross-origin browser POST requests. It has no built-in client authentication. For remote access, explicitly set the listen address and protect it with an authenticated reverse proxy and firewall, especially in readwrite mode. All MCP clients connected to one server process share that process's configured Microsoft identity.
Development
Requires Go 1.27.3 or newer (see go.mod). The full local check also requires Docker,
Task, and GoReleaser.
go build ./...
go test ./...
Using Task:
task build
task format
task test
task vet
task lint
task release-check
task check
task check runs the build, tests, go vet, the pinned golangci-lint Docker
image, and GoReleaser configuration validation.
Release
This repository includes GitHub Actions workflows for test and release:
.github/workflows/test.ymltests Linux, macOS, and Windows, and separately checks formatting, module tidiness,go vet, race-enabled tests, golangci-lint, and a complete GoReleaser snapshot..github/workflows/release.ymlreruns the tests, publishes GoReleaser artifacts when av*tag is pushed, and creates a GitHub artifact attestation fromchecksums.txt.
To create and push a release tag locally:
task release-tag TAG=v0.1.0
Or use the split flow:
task tag TAG=v0.1.0
task push-tag TAG=v0.1.0
GoReleaser is configured in .goreleaser.yaml to build teams-mcp for Linux,
macOS, and Windows on amd64 and arm64, publish archives, and attach
checksums.txt to the GitHub release. It also injects the tag version into the
binary and MCP server metadata, trims local build paths, and uses the commit
timestamp for reproducible build metadata.
Tests cover configuration and mode gating, token handling, all Graph endpoint families against local HTTP mocks, pagination URL validation, Graph error mapping, and end-to-end MCP smoke tests over stdio and streamable HTTP.
License
MIT — see LICENSE.
teams MCP questions
What tools does teams MCP provide?
It exposes 25 tools, including teams_get_current_user, teams_get_user, teams_list_users, teams_list_joined_teams, teams_list_channels.
How can I send messages using this server?
To send messages, you must set the TEAMS_MODE environment variable to 'readwrite'.
What is the recommended authentication method?
Device-code OAuth is recommended because it allows for delegated user permissions required for sending messages.
Can I use client credentials for sending messages?
No, client-credentials authentication is rejected in readwrite mode because it cannot perform normal Teams message sends.
Does the server support searching messages?
Yes, it provides a tool to search channel and chat messages using free text, provided you use delegated authentication.