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
1. Login and Token Management
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/incomingfor 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
.envvalues - 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=truefor local testing without real Teams
References
- Beyond Quacking: Deep Integration of Language Models and RAG into DuckDB (FlockMTL)
- Model Context Protocol documentation
- Microsoft Graph API docs
- PostgreSQL with pgvector extension
For full product details, see specs/app-spec.md.