Microsoft Teams & Outlook MCP Server

An MCP (Model Context Protocol) server that provides access to Microsoft Teams chats/channels, Outlook emails, calendar events, and SharePoint files via the Microsoft Graph API.

Use natural language in Claude Code, Codex CLI, AGY, Hermes Agent, VS Code, Claude Desktop, or any MCP client to read Teams messages, search emails, manage calendar events, browse files, and more.

Features

• Teams — List teams/channels, read/send/reply channel messages, create/read/send 1:1 & group chats
• Outlook — List/read/search/send/reply/forward emails, drafts, attachments, list mail folders
• Calendar — List/create/update/delete events, recurring events, reminders, respond to invitations
• SharePoint — List channel files, read file contents (text/xlsx), build & search file index
• Attachments — List & extract text from email and Teams message attachments (xlsx/hwp/csv/txt), or download any file to disk
• People — Search users across the organization
• Utilities — Unread summary, auth status, version update check
• Auth — Device Code Flow authentication directly from MCP or CLI
• Web Transport — SSE and streamable-http support for remote access from Claude Desktop, Claude web, and other MCP clients

Prerequisites

1. Register an Azure AD App

1. Go to Azure Portal > Azure Active Directory > App registrations > New registration
2. Set Redirect URI to https://login.microsoftonline.com/common/oauth2/nativeclient (Mobile and desktop applications)
3. Under Certificates & secrets, create a client secret
4. Under API permissions, add these Microsoft Graph delegated permissions:

1. Click Grant admin consent

2. Note Your Credentials

You will need these three values:

• MS_CLIENT_ID — Application (client) ID
• MS_CLIENT_SECRET — Client secret value
• MS_TENANT_ID — Directory (tenant) ID

3. Install uv

This project can run through uvx without a separate installation. If you prefer to install the ms-teams-mcp command with pip, skip this step and see pip Install (No venv).

Linux / macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Restart your terminal, then verify: uvx --version

Installation & Usage

Claude Code

No pre-installation needed for this MCP server — uvx automatically downloads and runs the package.

Linux / macOS:

claude mcp add ms-teams \
  -s user \
  -e MS_CLIENT_ID=<your-client-id> \
  -e MS_CLIENT_SECRET=<your-client-secret> \
  -e MS_TENANT_ID=<your-tenant-id> \
  -- uvx --from "git+https://github.com/3hs-labs/ms-teams-mcp.git" ms-teams-mcp

Windows (PowerShell):

claude mcp add ms-teams `
  -s user `
  -e MS_CLIENT_ID=<your-client-id> `
  -e MS_CLIENT_SECRET=<your-client-secret> `
  -e MS_TENANT_ID=<your-tenant-id> `
  -- uvx.cmd --from "git+https://github.com/3hs-labs/ms-teams-mcp.git" ms-teams-mcp

Verify the server is configured with claude mcp list.

Codex CLI

Codex stores MCP configuration in ~/.codex/config.toml, shared by Codex CLI and the Codex IDE extension.

Linux / macOS:

codex mcp add ms-teams \
  --env MS_CLIENT_ID=<your-client-id> \
  --env MS_CLIENT_SECRET=<your-client-secret> \
  --env MS_TENANT_ID=<your-tenant-id> \
  -- uvx --from "git+https://github.com/3hs-labs/ms-teams-mcp.git" ms-teams-mcp

Windows (PowerShell):

codex mcp add ms-teams `
  --env MS_CLIENT_ID=<your-client-id> `
  --env MS_CLIENT_SECRET=<your-client-secret> `
  --env MS_TENANT_ID=<your-tenant-id> `
  -- uvx.cmd --from "git+https://github.com/3hs-labs/ms-teams-mcp.git" ms-teams-mcp

Windows Note: If uvx is not found, use uvx.cmd or the full path %USERPROFILE%\.local\bin\uvx.cmd.

Verify the server is configured with codex mcp list.

AGY / Google Antigravity

Open AGY's MCP manager and edit the raw MCP JSON configuration, then add:

{
  "mcpServers": {
    "ms-teams": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/3hs-labs/ms-teams-mcp.git",
        "ms-teams-mcp"
      ],
      "env": {
        "MS_CLIENT_ID": "<your-client-id>",
        "MS_CLIENT_SECRET": "<your-client-secret>",
        "MS_TENANT_ID": "<your-tenant-id>"
      }
    }
  }
}

Windows: Use "command": "uvx.cmd" if uvx is not found.

Hermes Agent

Add to ~/.hermes/config.yaml under the mcp_servers key:

mcp_servers:
  ms-teams-mcp:
    command: uvx
    args:
      - ms-teams-mcp
    env:
      MS_CLIENT_ID: <your-client-id>
      MS_CLIENT_SECRET: <your-client-secret>
      MS_TENANT_ID: <your-tenant-id>

Then verify with:

hermes mcp list               # Should show ms-teams-mcp as ✓ enabled
hermes mcp test ms-teams-mcp  # Should report Connected + 33 tools

Note: Do not add ms-teams-mcp to plugins.enabled — it has no plugin.yaml and will produce a warning. Use mcp_servers instead.

On first use, ask Hermes to call the authenticate tool — it will guide you through Device Code Flow login in your browser.

VS Code

Add to .vscode/mcp.json in your project root (or under "mcp" key in user settings.json for global access):

{
  "servers": {
    "ms-teams": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/3hs-labs/ms-teams-mcp.git",
        "ms-teams-mcp"
      ],
      "env": {
        "MS_CLIENT_ID": "<your-client-id>",
        "MS_CLIENT_SECRET": "<your-client-secret>",
        "MS_TENANT_ID": "<your-tenant-id>"
      }
    }
  }
}

Windows: Use "command": "uvx.cmd" if uvx is not found.

Claude Desktop

Add to your config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ms-teams": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/3hs-labs/ms-teams-mcp.git",
        "ms-teams-mcp"
      ],
      "env": {
        "MS_CLIENT_ID": "<your-client-id>",
        "MS_CLIENT_SECRET": "<your-client-secret>",
        "MS_TENANT_ID": "<your-tenant-id>"
      }
    }
  }
}

Windows: Replace "command": "uvx" with "command": "uvx.cmd" if uvx is not found.

pip Install (No venv)

Install directly from GitHub without creating a virtual environment.

Recommended user-site install:

python3 -m pip install --user "git+https://github.com/3hs-labs/ms-teams-mcp.git"

Verify the command is available:

ms-teams-mcp --version

If ms-teams-mcp: command not found appears, make sure your user scripts directory is on PATH:

export PATH="$HOME/.local/bin:$PATH"

To make that permanent for Bash:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

If your system Python allows global installs, you can install without --user:

python3 -m pip install "git+https://github.com/3hs-labs/ms-teams-mcp.git"

On recent Ubuntu/Debian systems, global pip installs may be blocked by the externally managed environment policy. Prefer --user; if you intentionally want to install into the system Python, you may need:

python3 -m pip install --break-system-packages "git+https://github.com/3hs-labs/ms-teams-mcp.git"

Run the server directly:

ms-teams-mcp                  # stdio MCP server
ms-teams-mcp serve            # streamable-http server
ms-teams-mcp serve --transport sse

Register the installed command with your MCP client:

#### Claude Code

claude mcp add ms-teams \
  -s user \
  -e MS_CLIENT_ID=<your-client-id> \
  -e MS_CLIENT_SECRET=<your-client-secret> \
  -e MS_TENANT_ID=<your-tenant-id> \
  -- ms-teams-mcp

#### Codex CLI

codex mcp add ms-teams \
  --env MS_CLIENT_ID=<your-client-id> \
  --env MS_CLIENT_SECRET=<your-client-secret> \
  --env MS_TENANT_ID=<your-tenant-id> \
  -- ms-teams-mcp

For AGY, use the same JSON shown above but replace "command": "uvx" and the "args" array with "command": "ms-teams-mcp".

For Hermes Agent, use the YAML shown above but replace the command with "ms-teams-mcp" and remove the args list.

Direct Hermes Agent example:

mcp_servers:
  ms-teams-mcp:
    command: ms-teams-mcp
    env:
      MS_CLIENT_ID: <your-client-id>
      MS_CLIENT_SECRET: <your-client-secret>
      MS_TENANT_ID: <your-tenant-id>

Authentication

On first use, call the authenticate tool from your MCP client — it will provide a Device Code Flow URL to sign in via your browser.

Alternatively, you can authenticate from the CLI before starting:

# Using uvx
uvx --from "git+https://github.com/3hs-labs/ms-teams-mcp.git" \
  ms-teams-mcp auth \
  --client-id <your-client-id> \
  --client-secret <your-client-secret> \
  --tenant-id <your-tenant-id>

# Using pip install
ms-teams-mcp auth \
  --client-id <your-client-id> \
  --client-secret <your-client-secret> \
  --tenant-id <your-tenant-id>

Token is cached at ~/.ms_mcp_token.json and silently renewed on subsequent runs.

Upgrade

# uvx — clear cache, re-pulls latest from GitHub on next run
uv cache clean

# pip — force reinstall from GitHub
python3 -m pip install --user --upgrade --force-reinstall "git+https://github.com/3hs-labs/ms-teams-mcp.git"

The server automatically checks for updates on startup (once per 24h) by reading the version in the repo's pyproject.toml on GitHub, and notifies via stderr. You can also call the check_update tool from any MCP client.

Verify & Remove

# Claude Code
claude mcp list
claude mcp remove ms-teams

# Codex CLI
codex mcp list
codex mcp remove ms-teams

For AGY, open the MCP manager or raw MCP JSON configuration and remove the ms-teams entry.

For Hermes Agent, remove the ms-teams entry under mcp_servers and reload with /reload-mcp.

Available MCP Tools (48)

All list tools support top, skip, and next_link parameters for pagination.

Example Prompts

Teams — Channels

> Show my Teams list
> Show channels in the "Engineering" team
> Show the last 10 messages in the "General" channel of "Project A" team
> Send "Build completed successfully" to the #releases channel
> Reply to the latest message in #general with "Thanks for the update!"

Teams — Chats

> Show my recent chats
> Show messages from my chat with Sarah
> Send "Are you available for a quick call?" to my chat with David
> Create a group chat with [email protected] and [email protected] about "Q2 Planning"
> Search Teams messages for "budget" from [email protected] sent after June 1

Outlook — Email

> Check my inbox for today's emails
> Show my unread emails
> Read the latest email from my manager
> Search emails for "quarterly report" from last week
> Send an email to [email protected] with subject "Project Update" and summarize today's progress
> Reply to the latest email from Sarah saying "I'll review it by EOD"
> Forward the budget email to the finance team at [email protected]
> Draft an email to the team about tomorrow's outage, but don't send it yet
> Send the report.pdf in ~/Downloads to [email protected] with subject "Q2 Report"
> Show my mail folders

Calendar

> Show my calendar for this week
> What meetings do I have tomorrow?
> Create a meeting with [email protected] tomorrow at 2pm for 1 hour about "Design Review"
> Schedule a Teams online meeting with the frontend team next Monday 10am-11am
> Create a weekly recurring standup every weekday at 9:30am starting next Monday
> Set up a monthly team sync on the first Tuesday of each month
> Remind me about the report deadline at 3pm tomorrow
> Move my 2pm meeting to 4pm
> Cancel the design review meeting on Friday
> Accept the sprint planning invitation; decline the optional sync

Files

> Show files in the "General" channel of "Project A" team
> Read the project-plan.xlsx file from the Documents channel
> Build an index of all my accessible files
> Search my file index for "budget"
> Download the attachment from the latest email to ~/Downloads

People & Utilities

> Search for a user named "Kim" in the organization
> Find the email address of someone in the marketing team
> Summarize my unread emails and chat messages
> Check if there's a newer version of the MCP server

Combined Workflows

> Check my unread messages and emails, then give me a morning briefing
> Find all emails about "Project X", summarize them, and send a status update to the team channel
> Look at my calendar for next week and find a free slot for a 1-hour meeting
> Read the latest messages in #engineering and reply with a summary of today's deploy
> Search for "budget" in my emails and files, then compile the key numbers

<details> <summary><strong>한국어 사용 예시</strong></summary>

Teams — 채널

> 내 팀 목록 보여줘
> "개발팀" 팀의 채널 목록 보여줘
> "프로젝트A" 팀의 "일반" 채널 최근 메시지 10개 보여줘
> #releases 채널에 "빌드 완료되었습니다" 메시지 보내줘
> #general 최신 메시지에 "확인했습니다, 감사합니다!" 답장해줘

Teams — 채팅

> 최근 채팅 목록 보여줘
> 김민수님과의 채팅 내용 보여줘
> 이영희님에게 "잠깐 통화 가능하신가요?" 메시지 보내줘
> [email protected], [email protected]과 "2분기 기획" 주제로 그룹 채팅 만들어줘

Outlook — 메일

> 오늘 받은 메일 확인해줘
> 안 읽은 메일 보여줘
> 팀장님한테 온 최신 메일 읽어줘
> 지난주 "분기 보고서" 관련 메일 검색해줘
> [email protected]에게 "프로젝트 현황" 제목으로 오늘 진행 상황 정리해서 메일 보내줘
> 김과장님 메일에 "오늘 중으로 검토하겠습니다" 답장해줘
> 예산 관련 메일을 재무팀 [email protected]으로 전달해줘
> 내일 장애 관련 메일 초안만 작성해줘 (아직 보내지 말고)
> ~/Downloads의 report.pdf를 [email protected]에게 "Q2 보고서" 제목으로 보내줘
> 메일 폴더 목록 보여줘

캘린더

> 이번 주 일정 보여줘
> 내일 회의 뭐 있어?
> 내일 오후 2시에 [email protected]과 1시간 "디자인 리뷰" 회의 잡아줘
> 다음 주 월요일 오전 10시~11시 프론트엔드 팀 Teams 온라인 회의 만들어줘
> 다음 주 월요일부터 매일 오전 9시 30분 스탠드업 반복 일정 만들어줘
> 매월 첫째 화요일에 팀 싱크 회의 설정해줘
> 내일 오후 3시에 보고서 마감 리마인더 설정해줘
> 오후 2시 회의를 4시로 변경해줘
> 금요일 디자인 리뷰 회의 취소해줘
> 스프린트 플래닝 초대는 수락하고, 선택 회의는 거절해줘

파일

> "프로젝트A" 팀 "일반" 채널의 파일 목록 보여줘
> Documents 채널의 project-plan.xlsx 파일 읽어줘
> 내가 접근 가능한 모든 파일 인덱스 만들어줘
> 파일 인덱스에서 "예산" 검색해줘
> 최신 메일의 첨부파일을 ~/Downloads에 다운로드해줘

사용자 & 유틸리티

> 조직에서 "김" 이름 가진 사용자 검색해줘
> 마케팅팀 누군가의 이메일 주소 찾아줘
> 안 읽은 메일이랑 채팅 메시지 요약해줘
> MCP 서버 새 버전 있는지 확인해줘

복합 시나리오

> 안 읽은 메시지랑 메일 확인해서 오늘 아침 브리핑 해줘
> "프로젝트X" 관련 메일 전부 찾아서 요약하고, 팀 채널에 현황 공유해줘
> 다음 주 캘린더 확인하고 1시간짜리 회의 가능한 시간 찾아줘
> #engineering 최신 메시지 읽고 오늘 배포 내용 요약해서 답장해줘
> 메일이랑 파일에서 "예산" 검색해서 주요 수치 정리해줘

</details>

Web Transport (SSE / Streamable HTTP)

In addition to the default stdio mode, the server can run as an HTTP service — enabling remote connections from Claude Desktop, Claude web (claude.ai), and other MCP clients.

Quick Start

# Start with streamable-http (default web transport)
ms-teams-mcp serve

# Start with SSE transport
ms-teams-mcp serve --transport sse

# Custom host/port (default: 127.0.0.1:7979)
ms-teams-mcp serve --host 0.0.0.0 --port 9000

Claude Desktop (SSE)

Update your Claude Desktop config to connect via URL instead of launching a subprocess:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ms-teams": {
      "url": "http://localhost:7979/sse"
    }
  }
}

Then start the server separately:

MS_CLIENT_ID=<id> MS_CLIENT_SECRET=<secret> MS_TENANT_ID=<tenant> \
  ms-teams-mcp serve --transport sse

Claude Web (claude.ai)

Claude web requires streamable-http over HTTPS on a public URL. You need a Pro, Team, or Enterprise plan.

1. Start the server:

ms-teams-mcp serve --host 0.0.0.0 --port 7979

2. Set up a reverse proxy with HTTPS (e.g., nginx + Let's Encrypt):

server {
    listen 443 ssl;
    server_name mcp.your-domain.com;

    ssl_certificate     /etc/letsencrypt/live/mcp.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:7979;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

3. Connect from Claude web:

Go to Claude.ai → Settings → MCP Connectors → Add → enter your server URL:

https://mcp.your-domain.com/mcp

Transport Comparison

Note: The server uses a single token cache (~/.ms_mcp_token.json), so all clients connecting to the same server share one Microsoft account. For per-user access, each user should run their own server instance.

Troubleshooting

Project Structure

├── ms_teams_mcp/
│   ├── __init__.py    # Package init
│   └── server.py      # MCP server (single-file architecture)
├── tests/
│   └── test_server.py # pytest suite (tool formatting, error handling, retries)
├── pyproject.toml     # Package config & dependencies
├── CLAUDE.md          # Claude Code instructions
└── README.md

License

MIT