home / mcp / teams mcp server

Teams MCP Server

Bridges Microsoft Teams with MCP clients, providing persistent storage and hybrid search via an MCP server.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "imoon-mcp-teams": {
      "url": "http://localhost:8090/",
      "headers": {
        "DEMO_MODE": "false",
        "TOKEN_PATH": "db/token_cache.json",
        "DUCKDB_PATH": "db/teams_mcp.duckdb",
        "POSTGRES_DB": "mcp_ir",
        "POLL_INTERVAL": "10",
        "POSTGRES_USER": "postgres",
        "IR_SERVER_HOST": "ir_server",
        "IR_SERVER_PORT": "8090",
        "OPENAI_API_KEY": "sk-...",
        "AZURE_CLIENT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "AZURE_TENANT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "POSTGRES_PASSWORD": "postgres",
        "AZURE_APP_OBJECT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "AZURE_CLIENT_SECRET": "your-secret"
      }
    }
  }
}

You can connect Microsoft Teams with MCP-compatible clients through a pure MCP server that stores chat history, enables advanced search, and streams live events. This server lets you run a single Teams-connected bot, index conversations, and query them with hybrid semantic and lexical search, all via MCP tools, resources, and events instead of REST endpoints.

How to use

You interact with the MCP server using a rich CLI MCP client or your own MCP-compatible tooling. Start the server, log in, and then list chats, fetch messages, search content with hybrid search, and stream live updates as new messages arrive. You can also connect to the IR server to run advanced searches over your stored Teams conversations.

Typical workflows you can perform include:

How to install

Prerequisites you need before installation:

Python 3.9+
pip
Docker and Docker Compose (for containerized deployment)

Option 1: Local Installation

# 1. Clone the repository
git clone <your-repo-url>
cd mcp-teams

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure environment variables
cp .env.template .env
# Edit .env and fill in your Azure AD and other settings

Option 2: Docker Deployment (Recommended)

# 1. Clone the repository
git clone <your-repo-url>
cd mcp-teams

# 2. Configure environment variables
cp .env.template .env
# Edit .env and fill in your settings

3. Build and start services using Docker Compose

docker-compose up -d

Configuration and environment variables

The server relies on a set of environment variables to connect to Azure AD, manage storage, and configure search and IR behavior. Typical variables you will set in a .env file include Azure credentials, paths for storage, and IR server settings.

# Example environment variables
AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_CLIENT_SECRET=your-secret
AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_APP_OBJECT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DUCKDB_PATH=db/teams_mcp.duckdb
TOKEN_PATH=db/token_cache.json
POLL_INTERVAL=10
DEMO_MODE=false
OPENAI_API_KEY=sk-...
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=mcp_ir
IR_SERVER_HOST=ir_server
IR_SERVER_PORT=8090

Available tools

login

Authenticate with the MCP server and manage tokens for CLI access.

list_chats

List available Teams chats connected to the MCP server.

get_messages

Fetch messages from a specific chat by chat_id.

send_message

Send a message to a chat via MCP CLI.

create_chat

Create a new 1:1 chat with a specified user.

search_messages

Perform a hybrid search over stored messages using BM25 and vector search.

stream

Subscribe to live incoming messages and stream updates.