Teams Messenger MCP App

This project implements a pure Model Context Protocol (MCP) server that bridges Microsoft Teams and MCP-compatible clients (LLMs, agentic frameworks, and a rich CLI MCP client). All features are exposed via MCP tools, resources, and events—no REST API endpoints.

Features

Microsoft Teams chat/message integration via MCP
PostgreSQL-based Information Retrieval (IR) server for advanced search capabilities
Persistent storage in DuckDB for chat/message history
Hybrid semantic and lexical search (BM25 + vector, FlockMTL-style)
CLI for login/token management and a rich MCP client for local testing
Polling-based event emission for new messages
Live event streaming and search for LLMs and CLI
Single-agent (bot) account, not multi-user

Architecture

+-------------------+      +-------------------+      +-------------------+
|   CLI MCP Client  |<---->|    MCP Server     |<---->|  Microsoft Teams  |
| (rich terminal UI)|      | (Python, FastMCP) |      |  (Graph API)      |
+-------------------+      +-------------------+      +-------------------+
         |                        |                          
         |                        v                          
         |                +-------------------+      +-------------------+
         |                |     DuckDB DB     |      |    IR Server      |
         |                +-------------------+      | (PostgreSQL, API) |
                                                     +-------------------+
                                                              |
                                                              v
                                                     +-------------------+
                                                     |  PostgreSQL DB    |
                                                     |  (with pgvector)  |
                                                     +-------------------+

All chat/message/search logic is via MCP tools/resources/events
Teams MCP server uses DuckDB for message storage
IR server provides advanced search capabilities with PostgreSQL and pgvector
IR server exposes an HTTP API for MCP server communication

Installation

Requirements

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

Copy the template and fill in your Azure AD/Teams credentials:

cp .env.template .env
# Edit .env and fill in your Azure AD and other settings

See the table below for variable descriptions.

Option 2: Docker Deployment (Recommended)

1. Clone the repository

git clone <your-repo-url>
cd mcp-teams

2. Configure environment variables

Copy the template and fill in your credentials:

cp .env.template .env
# Edit .env and fill in your settings

3. Build and start services

docker-compose up -d

Environment Variables (.env)

Variable	Description	Example / Default
AZURE_CLIENT_ID	Azure AD Application (client) ID	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
AZURE_CLIENT_SECRET	Azure AD Application secret	`your-secret`
AZURE_TENANT_ID	Azure AD Tenant ID	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
AZURE_APP_OBJECT_ID	Azure AD Application object ID	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
DUCKDB_PATH	Path to DuckDB database file	`db/teams_mcp.duckdb`
TOKEN_PATH	Path to store persistent token cache	`db/token_cache.json`
POLL_INTERVAL	Polling interval (seconds) for new messages	`10`
DEMO_MODE	Set to `true` for mock/demo mode (no real Teams API calls)	`false`
OPENAI_API_KEY	OpenAI API key for embedding generation	`sk-...`
POSTGRES_USER	PostgreSQL username	`postgres`
POSTGRES_PASSWORD	PostgreSQL password	`postgres`
POSTGRES_DB	PostgreSQL database name	`mcp_ir`
IR_SERVER_HOST	IR server hostname	`ir_server`
IR_SERVER_PORT	IR server port	`8090`

Running the MCP Server

Local Mode (without Docker)

python mcp_server/server.py

Docker Mode (All Services)

docker-compose up -d

To check logs:

docker-compose logs -f teams_mcp  # Teams MCP server logs
docker-compose logs -f ir_server  # IR server logs

Demo Mode (no real Teams API calls)

Set DEMO_MODE=true in your .env and run as above.

CLI Usage

python cli/login.py login
python cli/login.py status
python cli/login.py logout

2. Rich CLI MCP Client

All commands below use the MCP stdio protocol to talk to the server.

List chats

python cli/mcp_client.py list_chats

Get messages from a chat

python cli/mcp_client.py get_messages <chat_id>

Send a message

python cli/mcp_client.py send_message <chat_id> "Hello from CLI!"

Create a new 1:1 chat

python cli/mcp_client.py create_chat <user_id_or_email>

Search messages (hybrid, BM25, or vector)

python cli/mcp_client.py search_messages "project update" --mode hybrid --top_k 5

Stream new incoming messages (live event subscription)

python cli/mcp_client.py stream

IR Server Usage

The IR server provides advanced search capabilities with PostgreSQL and pgvector. It exposes an HTTP API for MCP server communication.

IR Server API Endpoints

1. Health Check

GET http://localhost:8090/

2. List Available Tools

GET http://localhost:8090/api/tools

3. Search Content

POST http://localhost:8090/api/tools/search

Body:

{
  "query": "your search query",
  "search_type": "hybrid",
  "limit": 10
}

4. Index Content

POST http://localhost:8090/api/tools/index_content

Body:

{
  "content": "Text content to index",
  "source_type": "teams",
  "metadata": {
    "author": "User Name",
    "created": "2025-04-01T12:00:00Z"
  }
}

For more detailed IR server documentation, see ir/README.md.

Search and Event Streaming

Hybrid search: Combines BM25 and vector search with LLM reranking
Live streaming: Subscribe to messages/incoming for real-time updates

Development & Extension

Add new MCP tools/resources in mcp_server/server.py
Extend Teams integration in teams/graph.py
Modify IR capabilities in the IR server
Add analytics, summarization, or RAG features using DuckDB, PostgreSQL, and LLMs
Use the CLI as a test harness for all MCP features

Troubleshooting & FAQ

Login fails: Check your Azure AD credentials and .env values
No messages appear: Ensure polling is running and your bot account is in the Teams chat
DuckDB errors: Check file permissions and paths in .env
IR server not responding: Check Docker logs and ensure the container is running
Demo mode: Set DEMO_MODE=true for local testing without real Teams

References

For full product details, see specs/app-spec.md.

This server cannot be installed

security - not tested

license - not found

quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A Model Context Protocol server that bridges Microsoft Teams with MCP-compatible clients (LLMs, agentic frameworks, CLI), enabling chat integration, message search, and event streaming without traditional REST API endpoints.

Related MCP Servers

MCP Server Example
alejandro-ao
A
security
A
license
A
quality
An educational implementation of a Model Context Protocol server that demonstrates how to build a functional MCP server for integrating with various LLM clients like Claude Desktop.
Last updated -
1
88
Python
MIT License
Dynamics 365 MCP Server
srikanth-paladugula
A
security
A
license
A
quality
A Model Context Protocol server that enables interaction with Microsoft Dynamics 365 CRM from Claude Desktop, allowing users to retrieve, create, and update CRM data through natural language.
Last updated -
5
4
TypeScript
MIT License
Hello World MCP Server
jageenshukla
-
security
A
license
-
quality
A demonstration server that implements the Model Context Protocol (MCP) SDK, providing tools and endpoints for server-sent events and message handling.
Last updated -
27
TypeScript
MIT License
Teams Messenger MCP App
imoon
-
security
-
license
-
quality
A Model Context Protocol server that bridges Microsoft Teams and MCP-compatible clients, enabling chat integration, message handling, and advanced search capabilities without REST API endpoints.
Last updated -
Python

View all related MCP servers