mcp-teams-server

To install the server locally, ensure you have uv and Python 3.10 installed. Clone the repository, create a virtual environment, and sync dependencies using the following commands:

git clone [repository-url]
cd mcp-teams-server

uv venv
uv sync --frozen --all-extras --dev

After Entra ID registration, register an Azure Bot. Use your existing TEAMS_APP_ID during this registration process.

Note: You do not need to deploy a web app to Azure or the internet. The MCP server acts as a client to the Azure Bot Framework REST API. However, you must connect the bot to the Teams channel within the Azure Bot configuration to enable communication.

To run integration tests, you must set up specific test environment variables to provide context for the test execution:

• TEST_THREAD_ID: timestamp of the thread id
• TEST_MESSAGE_ID: timestamp of the message id
• TEST_USER_NAME: test user name

Then execute the following command:

uv run pytest -m integration

To make the bot available in Teams, you must publish a Teams Application. You have two options:

Option 1: Use the provided skeleton

Use the files in the /app directory of this repository.

1. Replace all instances of {{MICROSOFT_APP_ID}} with your TEAMS_APP_ID.
2. Replace the default icons with your own.
3. Zip the directory and upload it to Microsoft Teams.

Option 2: Use the Teams Developer Portal

Create the application via the Teams developer portal. If using this method, you must manually configure the 'bot feature' and add the following required permissions:

• TeamMember.Read.Group
• ChannelMessage.Read.Group
• ChannelMessage.Send.Group
• ChannelSettings.Read.Group
• ChannelMember.Read.Group
• Member.Read.Group
• Owner.Read.Group

Finally, the application must be installed into a specific Teams Group.

For local development, you can use the uv package manager to run the server directly. Ensure you have uv and Python 3.10 installed. Add this configuration to your MCP settings file, providing the required Teams environment variables.

{
  "mcpServers": {
    "msteams": {
      "command": "uv",
      "args": [
        "run",
        "mcp-teams-server"
      ],
      "env": {
        "TEAMS_APP_ID": "<fill_me_with_proper_uuid>",
        "TEAMS_APP_PASSWORD": "<fill_me_with_proper_uuid>",
        "TEAMS_APP_TYPE": "<fill_me_with_proper_uuid>",
        "TEAMS_APP_TENANT_ID": "<fill_me_with_proper_uuid>",
        "TEAM_ID": "<fill_me_with_proper_uuid>",
        "TEAMS_CHANNEL_ID": "<fill_me_with_proper_channel_id>"
      }
    }
  }
}

To restrict the MCP server to specific channels, you must extract the groupId and channelId from your Microsoft Teams URL.

Example URL format: https://teams.microsoft.com/l/channel/[TEAMS_CHANNEL_ID]/McpBot?groupId=[TEAM_ID]&tenantId=[TEAMS_APP_TENANT_ID]

Required environment variables:

• TEAM_ID: Extracted from the groupId parameter.
• TEAMS_CHANNEL_ID: Extracted from the channel segment of the URL.

The MCP server will read and post only within the specified TEAM_ID and will use TEAMS_CHANNEL_ID as the default channel.

You can use pre-built Docker images or build your own to run the MCP server.

### Pull pre-built image
```bash
docker pull ghcr.io/inditextech/mcp-teams-server:latest

Build your own image

docker build . -t inditextech/mcp-teams-server

Run the image

Basic run:

docker run -it inditextech/mcp-teams-server

Run with environment variables from an .env file:

docker run --env-file .env -it inditextech/mcp-teams-server

The MCP Teams Server requires specific environment variables to authenticate with Microsoft Teams and identify the target workspace. You can set these in your shell or an .env file. Use the sample.env file provided in the repository as a template.

TEAMS_APP_ID        # UUID for your MS Entra ID application ID
TEAMS_APP_PASSWORD  # Client secret
TEAMS_APP_TYPE      # SingleTenant or MultiTenant
TEAMS_APP_TENANT_ID # Tenant uuid in case of SingleTenant
TEAM_ID              # MS Teams Group Id or Team Id
TEAMS_CHANNEL_ID     # MS Teams Channel ID with url escaped chars

You can use the following natural language prompts to trigger the MCP Teams Server tools:

• "Please start a thread in teams with the following content..."
• "Please list members in team"
• "Please perform this task... and send results to a new thread in teams. Remember to mention '[User Name]'"
• "Please read latest team threads and reply to threads that mention '[Your bot name]'"