mcp-teams-reader 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# teams-mcp-server
+
+MCP Server for Microsoft Teams — search, read and summarize messages via Claude / AI assistants.
+
+## Features
+
+- List joined Teams and channels
+- Read channel messages (with time range filter)
+- List and read 1:1 / group chats
+- Search messages by keyword across chats and channels
+- Deep links to open messages in Teams
+
+## Quick Start
+
+```bash
+npx teams-mcp-server
+```
+
+## Setup
+
+### 1. Register an Azure AD App
+
+1. Go to [Azure Portal](https://portal.azure.com) → **App registrations** → **New registration**
+2. Set **Supported account types** to your org (single tenant)
+3. Under **Authentication**, enable **Allow public client flows** (for Device Code Flow)
+4. Under **API permissions**, add these **Delegated** permissions for Microsoft Graph:
+   - `Chat.Read`
+   - `ChannelMessage.Read.All`
+   - `Team.ReadBasic.All`
+   - `Channel.ReadBasic.All`
+   - `User.Read`
+5. Click **Grant admin consent** (or ask your admin)
+
+### 2. Configure MCP Client
+
+Add to your MCP client config (e.g. Claude Code `settings.json` or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "teams": {
+      "command": "npx",
+      "args": ["teams-mcp-server"],
+      "env": {
+        "TEAMS_CLIENT_ID": "your-azure-app-client-id",
+        "TEAMS_TENANT_ID": "your-azure-tenant-id"
+      }
+    }
+  }
+}
+```
+
+### 3. Authenticate
+
+On first use, any tool call will return a Device Code login prompt. Open the URL in your browser, enter the code, and sign in. The token is cached locally for future use.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_my_teams` | List all Teams you've joined |
+| `list_channels` | List channels in a team |
+| `get_channel_messages` | Get channel messages (with optional time filter) |
+| `list_my_chats` | List recent 1:1 and group chats |
+| `get_chat_messages` | Get messages from a chat |
+| `search_messages` | Search messages by keyword across chats |
+| `search_channel_messages` | Search messages by keyword in a channel |
+
+## Development
+
+```bash
+git clone <repo-url>
+cd teams-mcp-server
+npm install
+cp .env.example .env  # fill in your Client ID and Tenant ID
+npm run dev
+```
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error thrown when device code authentication is needed.
+ * The message contains the device code instructions for the user.
+ */
+export declare class DeviceCodeRequiredError extends Error {
+    constructor(message: string);
+}
+/**
+ * Get an access token, using cached token if available.
+ * If device code auth is needed, throws DeviceCodeRequiredError
+ * with the auth instructions, and starts the flow in the background.
+ * On next call, if auth completed, returns the token.
+ */
+export declare function getAccessToken(): Promise<string>;

package/dist/auth.js

@@ -0,0 +1,128 @@
+import { PublicClientApplication, } from "@azure/msal-node";
+import { readFile, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import path from "path";
+const TOKEN_CACHE_PATH = path.join(import.meta.dirname ?? ".", "..", "token-cache.json");
+const SCOPES = [
+    "Chat.Read",
+    "ChannelMessage.Read.All",
+    "Team.ReadBasic.All",
+    "Channel.ReadBasic.All",
+    "User.Read",
+];
+let msalClient = null;
+// Background auth state
+let pendingAuthPromise = null;
+let pendingDeviceCodeMessage = null;
+function getConfig() {
+    const clientId = process.env.TEAMS_CLIENT_ID;
+    const tenantId = process.env.TEAMS_TENANT_ID;
+    if (!clientId || !tenantId) {
+        throw new Error("Missing TEAMS_CLIENT_ID or TEAMS_TENANT_ID environment variables");
+    }
+    return { clientId, tenantId };
+}
+async function getMsalClient() {
+    if (msalClient)
+        return msalClient;
+    const { clientId, tenantId } = getConfig();
+    msalClient = new PublicClientApplication({
+        auth: {
+            clientId,
+            authority: `https://login.microsoftonline.com/${tenantId}`,
+        },
+        cache: {
+            cachePlugin: {
+                beforeCacheAccess: async (ctx) => {
+                    if (existsSync(TOKEN_CACHE_PATH)) {
+                        const data = await readFile(TOKEN_CACHE_PATH, "utf-8");
+                        ctx.tokenCache.deserialize(data);
+                    }
+                },
+                afterCacheAccess: async (ctx) => {
+                    if (ctx.cacheHasChanged) {
+                        await writeFile(TOKEN_CACHE_PATH, ctx.tokenCache.serialize(), "utf-8");
+                    }
+                },
+            },
+        },
+    });
+    return msalClient;
+}
+/**
+ * Error thrown when device code authentication is needed.
+ * The message contains the device code instructions for the user.
+ */
+export class DeviceCodeRequiredError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DeviceCodeRequiredError";
+    }
+}
+/**
+ * Get an access token, using cached token if available.
+ * If device code auth is needed, throws DeviceCodeRequiredError
+ * with the auth instructions, and starts the flow in the background.
+ * On next call, if auth completed, returns the token.
+ */
+export async function getAccessToken() {
+    const client = await getMsalClient();
+    // Try silent acquisition first (cached token)
+    const accounts = await client.getTokenCache().getAllAccounts();
+    if (accounts.length > 0) {
+        try {
+            const result = await client.acquireTokenSilent({
+                account: accounts[0],
+                scopes: SCOPES,
+            });
+            if (result?.accessToken)
+                return result.accessToken;
+        }
+        catch {
+            // Silent acquisition failed, fall through to device code
+        }
+    }
+    // If there's a pending auth, check if it completed
+    if (pendingAuthPromise) {
+        try {
+            const token = await Promise.race([
+                pendingAuthPromise,
+                // Give it 2 seconds to check if already done
+                new Promise((_, reject) => setTimeout(() => reject(new Error("still_pending")), 2000)),
+            ]);
+            pendingAuthPromise = null;
+            pendingDeviceCodeMessage = null;
+            return token;
+        }
+        catch (err) {
+            if (err?.message === "still_pending") {
+                // Still waiting for user to authenticate
+                throw new DeviceCodeRequiredError(`⏳ 认证进行中，请先在浏览器中完成登录，然后再试一次。\n\n${pendingDeviceCodeMessage ?? ""}`);
+            }
+            // Auth failed, reset and try again
+            pendingAuthPromise = null;
+            pendingDeviceCodeMessage = null;
+        }
+    }
+    // Start device code flow in background
+    const deviceCodeRequest = {
+        scopes: SCOPES,
+        deviceCodeCallback: (response) => {
+            pendingDeviceCodeMessage = response.message;
+        },
+    };
+    pendingAuthPromise = client
+        .acquireTokenByDeviceCode(deviceCodeRequest)
+        .then((result) => {
+        if (!result?.accessToken) {
+            throw new Error("Failed to acquire access token");
+        }
+        return result.accessToken;
+    });
+    // Wait briefly for the device code callback to fire
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+    const message = pendingDeviceCodeMessage
+        ? `🔐 需要登录 Microsoft 账号：\n\n${pendingDeviceCodeMessage}\n\n完成登录后，请再次调用此工具。`
+        : "🔐 正在获取认证信息，请稍后再试...";
+    throw new DeviceCodeRequiredError(message);
+}

package/dist/graph.d.ts

@@ -0,0 +1,57 @@
+interface Team {
+    id: string;
+    displayName: string;
+    description?: string;
+}
+interface Channel {
+    id: string;
+    displayName: string;
+    description?: string;
+    webUrl?: string;
+}
+interface ChatMessage {
+    id: string;
+    createdDateTime: string;
+    body: {
+        content: string;
+        contentType: string;
+    };
+    from?: {
+        user?: {
+            displayName: string;
+            id: string;
+        };
+    };
+    webUrl?: string;
+    channelIdentity?: {
+        teamId: string;
+        channelId: string;
+    };
+}
+interface Chat {
+    id: string;
+    topic?: string;
+    chatType: string;
+    lastUpdatedDateTime?: string;
+    members?: Array<{
+        displayName?: string;
+    }>;
+}
+/** List all teams the user is a member of */
+export declare function listMyTeams(): Promise<Team[]>;
+/** List channels in a team */
+export declare function listChannels(teamId: string): Promise<Channel[]>;
+/** Get messages from a team channel, optionally filtered by date */
+export declare function getChannelMessages(teamId: string, channelId: string, since?: string, top?: number): Promise<ChatMessage[]>;
+/** List the user's 1:1 and group chats */
+export declare function listMyChats(top?: number): Promise<Chat[]>;
+/** Get messages from a 1:1 or group chat */
+export declare function getChatMessages(chatId: string, since?: string, top?: number): Promise<ChatMessage[]>;
+/** Search messages across chats using keyword */
+export declare function searchMessages(keyword: string, daysBack?: number): Promise<Array<ChatMessage & {
+    chatId: string;
+    chatTopic?: string;
+}>>;
+/** Build a deep link to a Teams message */
+export declare function buildTeamsLink(teamId: string, channelId: string, messageId: string): string;
+export {};

package/dist/graph.js

@@ -0,0 +1,78 @@
+import { getAccessToken } from "./auth.js";
+const GRAPH_BASE = "https://graph.microsoft.com/v1.0";
+async function graphFetch(endpoint) {
+    const token = await getAccessToken();
+    const res = await fetch(`${GRAPH_BASE}${endpoint}`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+        const errText = await res.text();
+        throw new Error(`Graph API error ${res.status}: ${errText}`);
+    }
+    return res.json();
+}
+/** List all teams the user is a member of */
+export async function listMyTeams() {
+    const data = await graphFetch("/me/joinedTeams");
+    return data.value;
+}
+/** List channels in a team */
+export async function listChannels(teamId) {
+    const data = await graphFetch(`/teams/${teamId}/channels`);
+    return data.value;
+}
+/** Get messages from a team channel, optionally filtered by date */
+export async function getChannelMessages(teamId, channelId, since, top = 50) {
+    let endpoint = `/teams/${teamId}/channels/${channelId}/messages?$top=${top}`;
+    const data = await graphFetch(endpoint);
+    let messages = data.value;
+    // Client-side filter by date if `since` is provided
+    if (since) {
+        const sinceDate = new Date(since);
+        messages = messages.filter((m) => new Date(m.createdDateTime) >= sinceDate);
+    }
+    return messages;
+}
+/** List the user's 1:1 and group chats */
+export async function listMyChats(top = 50) {
+    const data = await graphFetch(`/me/chats?$top=${top}`);
+    return data.value;
+}
+/** Get messages from a 1:1 or group chat */
+export async function getChatMessages(chatId, since, top = 50) {
+    const data = await graphFetch(`/me/chats/${chatId}/messages?$top=${top}`);
+    let messages = data.value;
+    if (since) {
+        const sinceDate = new Date(since);
+        messages = messages.filter((m) => new Date(m.createdDateTime) >= sinceDate);
+    }
+    return messages;
+}
+/** Search messages across chats using keyword */
+export async function searchMessages(keyword, daysBack = 7) {
+    const chats = await listMyChats(50);
+    const since = new Date();
+    since.setDate(since.getDate() - daysBack);
+    const sinceISO = since.toISOString();
+    const results = [];
+    const lowerKeyword = keyword.toLowerCase();
+    // Search through recent chats
+    for (const chat of chats.slice(0, 20)) {
+        try {
+            const messages = await getChatMessages(chat.id, sinceISO, 50);
+            for (const msg of messages) {
+                if (msg.body.content.toLowerCase().includes(lowerKeyword)) {
+                    results.push({ ...msg, chatId: chat.id, chatTopic: chat.topic ?? undefined });
+                }
+            }
+        }
+        catch {
+            // Skip chats that error out
+        }
+    }
+    return results;
+}
+/** Build a deep link to a Teams message */
+export function buildTeamsLink(teamId, channelId, messageId) {
+    return `https://teams.microsoft.com/l/message/${channelId}/${messageId}?tenantId=&groupId=${teamId}&parentMessageId=${messageId}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { listMyTeams, listChannels, getChannelMessages, listMyChats, getChatMessages, searchMessages, buildTeamsLink, } from "./graph.js";
+import { DeviceCodeRequiredError } from "./auth.js";
+function handleError(err) {
+    if (err instanceof DeviceCodeRequiredError) {
+        return { content: [{ type: "text", text: err.message }], isError: true };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: `错误: ${msg}` }], isError: true };
+}
+function stripHtml(html) {
+    return html
+        .replace(/<[^>]*>/g, "")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .trim();
+}
+function formatDate(iso) {
+    return new Date(iso).toLocaleString("zh-CN", { timeZone: "Asia/Tokyo" });
+}
+const server = new McpServer({
+    name: "teams-mcp-server",
+    version: "1.0.0",
+});
+// ============ Tool: list_my_teams ============
+server.tool("list_my_teams", "列出我加入的所有 Teams 团队", {}, async () => {
+    try {
+        const teams = await listMyTeams();
+        const text = teams
+            .map((t) => `- **${t.displayName}** (ID: ${t.id})${t.description ? ` — ${t.description}` : ""}`)
+            .join("\n");
+        return {
+            content: [{ type: "text", text: text || "没有找到任何团队。" }],
+        };
+    }
+    catch (err) {
+        return handleError(err);
+    }
+});
+// ============ Tool: list_channels ============
+server.tool("list_channels", "列出某个团队下的所有频道", { team_id: z.string().describe("团队 ID，可通过 list_my_teams 获取") }, async ({ team_id }) => {
+    try {
+        const channels = await listChannels(team_id);
+        const text = channels
+            .map((c) => `- **${c.displayName}** (ID: ${c.id})${c.description ? ` — ${c.description}` : ""}`)
+            .join("\n");
+        return {
+            content: [{ type: "text", text: text || "该团队没有频道。" }],
+        };
+    }
+    catch (err) {
+        return handleError(err);
+    }
+});
+// ============ Tool: get_channel_messages ============
+server.tool("get_channel_messages", "获取团队频道的消息，可指定时间范围。用于总结频道讨论内容。", {
+    team_id: z.string().describe("团队 ID"),
+    channel_id: z.string().describe("频道 ID"),
+    since: z
+        .string()
+        .optional()
+        .describe("起始时间 ISO 格式，如 2026-03-06T00:00:00Z，不填则获取最近消息"),
+    limit: z.number().optional().default(50).describe("最大消息数，默认 50"),
+}, async ({ team_id, channel_id, since, limit }) => {
+    try {
+        const messages = await getChannelMessages(team_id, channel_id, since, limit);
+        if (messages.length === 0) {
+            return { content: [{ type: "text", text: "该时间范围内没有消息。" }] };
+        }
+        const text = messages
+            .map((m) => {
+            const sender = m.from?.user?.displayName ?? "Unknown";
+            const time = formatDate(m.createdDateTime);
+            const body = stripHtml(m.body.content);
+            const link = buildTeamsLink(team_id, channel_id, m.id);
+            return `**${sender}** (${time}):\n${body}\n[打开消息](${link})`;
+        })
+            .join("\n\n---\n\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `找到 ${messages.length} 条消息：\n\n${text}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return handleError(err);
+    }
+});
+// ============ Tool: list_my_chats ============
+server.tool("list_my_chats", "列出我最近的私聊和群聊", {
+    limit: z.number().optional().default(20).describe("返回数量，默认 20"),
+}, async ({ limit }) => {
+    try {
+        const chats = await listMyChats(limit);
+        const text = chats
+            .map((c) => {
+            const topic = c.topic || `(${c.chatType} chat)`;
+            const updated = c.lastUpdatedDateTime
+                ? formatDate(c.lastUpdatedDateTime)
+                : "";
+            return `- **${topic}** (ID: ${c.id}) — 最后更新: ${updated}`;
+        })
+            .join("\n");
+        return {
+            content: [{ type: "text", text: text || "没有找到聊天。" }],
+        };
+    }
+    catch (err) {
+        return handleError(err);
+    }
+});
+// ============ Tool: get_chat_messages ============
+server.tool("get_chat_messages", "获取某个私聊/群聊的消息", {
+    chat_id: z.string().describe("聊天 ID，可通过 list_my_chats 获取"),
+    since: z.string().optional().describe("起始时间 ISO 格式"),
+    limit: z.number().optional().default(50).describe("最大消息数"),
+}, async ({ chat_id, since, limit }) => {
+    try {
+        const messages = await getChatMessages(chat_id, since, limit);
+        if (messages.length === 0) {
+            return { content: [{ type: "text", text: "没有消息。" }] };
+        }
+        const text = messages
+            .map((m) => {
+            const sender = m.from?.user?.displayName ?? "Unknown";
+            const time = formatDate(m.createdDateTime);
+            const body = stripHtml(m.body.content);
+            return `**${sender}** (${time}):\n${body}`;
+        })
+            .join("\n\n---\n\n");
+        return {
+            content: [{ type: "text", text: `${messages.length} 条消息：\n\n${text}` }],
+        };
+    }
+    catch (err) {
+        return handleError(err);
+    }
+});
+// ============ Tool: search_messages ============
+server.tool("search_messages", "按关键词搜索最近的聊天消息（搜索私聊和群聊）", {
+    keyword: z.string().describe("搜索关键词"),
+    days_back: z.number().optional().default(7).describe("搜索最近几天，默认 7 天"),
+}, async ({ keyword, days_back }) => {
+    try {
+        const results = await searchMessages(keyword, days_back);
+        if (results.length === 0) {
+            return {
+                content: [
+                    { type: "text", text: `没有找到包含"${keyword}"的消息。` },
+                ],
+            };
+        }
+        const text = results
+            .map((m) => {
+            const sender = m.from?.user?.displayName ?? "Unknown";
+            const time = formatDate(m.createdDateTime);
+            const body = stripHtml(m.body.content);
+            const chatInfo = m.chatTopic ? `[${m.chatTopic}]` : `[Chat: ${m.chatId.slice(0, 8)}...]`;
+            const link = m.webUrl
+                ? m.webUrl
+                : `https://teams.microsoft.com/l/message/${m.chatId}/${m.id}?context=${encodeURIComponent(JSON.stringify({ contextType: "chat" }))}`;
+            return `${chatInfo} **${sender}** (${time}):\n${body}\n🔗 ${link}`;
+        })
+            .join("\n\n---\n\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `找到 ${results.length} 条包含"${keyword}"的消息：\n\n${text}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return handleError(err);
+    }
+});
+// ============ Tool: search_channel_messages ============
+server.tool("search_channel_messages", "在指定团队频道中按关键词搜索消息", {
+    team_id: z.string().describe("团队 ID"),
+    channel_id: z.string().describe("频道 ID"),
+    keyword: z.string().describe("搜索关键词"),
+    since: z.string().optional().describe("起始时间 ISO 格式"),
+}, async ({ team_id, channel_id, keyword, since }) => {
+    try {
+        const messages = await getChannelMessages(team_id, channel_id, since, 50);
+        const lowerKeyword = keyword.toLowerCase();
+        const matched = messages.filter((m) => stripHtml(m.body.content).toLowerCase().includes(lowerKeyword));
+        if (matched.length === 0) {
+            return {
+                content: [
+                    { type: "text", text: `频道中没有找到包含"${keyword}"的消息。` },
+                ],
+            };
+        }
+        const text = matched
+            .map((m) => {
+            const sender = m.from?.user?.displayName ?? "Unknown";
+            const time = formatDate(m.createdDateTime);
+            const body = stripHtml(m.body.content);
+            const link = buildTeamsLink(team_id, channel_id, m.id);
+            return `**${sender}** (${time}):\n${body}\n[打开消息](${link})`;
+        })
+            .join("\n\n---\n\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `找到 ${matched.length} 条匹配消息：\n\n${text}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return handleError(err);
+    }
+});
+// ============ Start Server ============
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Teams MCP Server is running");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "mcp-teams-reader",
+  "version": "1.0.0",
+  "description": "MCP Server for Microsoft Teams - search, read and summarize messages",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-teams-reader": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "microsoft-teams",
+    "teams",
+    "claude",
+    "ai",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "dependencies": {
+    "@azure/msal-node": "^2.16.0",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}