@mhdd_24/m365-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 mhdd_24
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# @mhdd_24/m365-mcp
+
+Custom MCP server for **Microsoft Outlook** and **Microsoft Teams** via the **Microsoft Graph API**. Built with the same architecture as `@mhdd_24/timelog-mcp`.
+
+Use it from Cursor, Claude Desktop, or any MCP-compatible client.
+
+---
+
+## Tools (10)
+
+| Tool | Domain | Description |
+|------|--------|-------------|
+| `whoami` | Profile | Signed-in user profile |
+| `list_inbox` | Outlook | Recent inbox messages |
+| `read_email` | Outlook | Read a message by ID |
+| `send_email` | Outlook | Send email |
+| `list_calendar` | Outlook | Calendar events for a date range |
+| `list_teams` | Teams | Joined teams |
+| `list_teams_chats` | Teams | Direct/group chats |
+| `send_teams_chat` | Teams | Message a chat |
+| `list_channels` | Teams | Channels in a team |
+| `send_channel_message` | Teams | Post to a channel |
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|--------|
+| **Node.js 18+** | Native `fetch` |
+| **Azure App Registration** | Public client (device code flow) |
+| **Graph API permissions** | See below |
+| **Admin consent** | May be required in your org |
+
+### Azure App Registration
+
+1. [Azure Portal](https://portal.azure.com) → **Entra ID** → **App registrations** → **New registration**
+2. Name: `Cursor M365 MCP`
+3. Supported account types: **Single tenant** (recommended)
+4. No redirect URI required for device code flow
+5. **Authentication** → Enable **Allow public client flows** → Yes
+6. **API permissions** → Microsoft Graph → **Delegated**:
+
+| Permission | Purpose |
+|--------------|---------|
+| `User.Read` | Profile |
+| `Mail.Read` | Read inbox |
+| `Mail.Send` | Send email |
+| `Calendars.Read` | Calendar |
+| `Chat.Read`, `Chat.ReadWrite`, `ChatMessage.Send` | Teams chats |
+| `Team.ReadBasic.All` | List teams |
+| `Channel.ReadBasic.All`, `ChannelMessage.Send` | Channels |
+
+7. **Grant admin consent** if required
+8. Copy **Application (client) ID** and **Directory (tenant) ID**
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/Mhdd-24/M365-MCP.git
+cd m365-mcp
+npm install
+npm run build
+```
+
+Or after publish:
+
+```bash
+npx @mhdd_24/m365-mcp
+```
+
+---
+
+## Configure Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "m365": {
+      "command": "npx",
+      "args": ["-y", "@mhdd_24/m365-mcp"],
+      "env": {
+        "M365_CLIENT_ID": "<azure-app-client-id>",
+        "M365_TENANT_ID": "<azure-tenant-id>"
+      }
+    }
+  }
+}
+```
+
+**Local development:**
+
+```json
+"command": "node",
+"args": ["C:/path/to/m365-mcp/dist/index.js"]
+```
+
+---
+
+## First-time sign-in
+
+On first tool call, the server prints a **device code** URL to stderr. Open the link, enter the code, and sign in with your work account.
+
+Or sign in ahead of time:
+
+```bash
+cp .env.example .env
+# fill M365_CLIENT_ID and M365_TENANT_ID
+npm run login
+```
+
+Token cache: `~/.m365-mcp/msal-cache.json`
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `M365_CLIENT_ID` | Yes | Azure app client ID |
+| `M365_TENANT_ID` | Yes | Azure tenant ID |
+| `M365_GRAPH_BASE_URL` | No | Default `https://graph.microsoft.com/v1.0` |
+| `M365_TOKEN_CACHE_PATH` | No | Custom token cache file path |
+
+---
+
+## Example prompts
+
+**Outlook**
+
+> List my unread emails.
+
+> Send an email to colleague@company.com — subject "Sprint review", body "Meeting at 3pm."
+
+> What's on my calendar today?
+
+**Teams**
+
+> List my Teams.
+
+> Send a Teams chat message: "PR is ready for review" to chat ID …
+
+> Post "Deploy complete" to the General channel in team …
+
+---
+
+## Project structure
+
+```
+m365-mcp/
+├── src/
+│   ├── index.ts
+│   ├── env.ts
+│   ├── config/m365.config.ts
+│   ├── interfaces/graph.ts
+│   ├── services/
+│   │   ├── authService.ts      ← OAuth device code + MSAL cache
+│   │   ├── graphClient.ts      ← Graph HTTP wrapper
+│   │   └── graphService.ts     ← Mail, calendar, Teams APIs
+│   ├── tools/                  ← MCP tool handlers
+│   └── scripts/login.ts
+├── package.json
+└── README.md
+```
+
+---
+
+## License
+
+ISC

package/dist/config/m365.config.js

@@ -0,0 +1,129 @@
+export const M365 = {
+    SERVER: {
+        NAME: '@mhdd_24/m365-mcp',
+        VERSION: '1.0.0',
+        STARTUP_MESSAGE: 'Microsoft 365 MCP Server Started',
+        FATAL_PREFIX: 'Fatal error:',
+    },
+    GRAPH: {
+        DEFAULT_BASE_URL: 'https://graph.microsoft.com/v1.0',
+        AUTHORITY_TEMPLATE: 'https://login.microsoftonline.com/{tenant}',
+        SCOPES: [
+            'User.Read',
+            'Mail.Read',
+            'Mail.Send',
+            'Calendars.Read',
+            'Chat.Read',
+            'Chat.ReadWrite',
+            'ChatMessage.Send',
+            'Team.ReadBasic.All',
+            'Channel.ReadBasic.All',
+            'ChannelMessage.Send',
+        ],
+    },
+    CACHE: {
+        DEFAULT_DIR: '.m365-mcp',
+        DEFAULT_FILE: 'msal-cache.json',
+    },
+    HTTP: {
+        SUCCESS_MIN: 200,
+        SUCCESS_MAX: 299,
+        ERROR_BODY_SLICE: 500,
+    },
+    LIMITS: {
+        DEFAULT_TOP: 25,
+        MAX_TOP: 50,
+        SUBJECT_SLICE: 120,
+        PREVIEW_SLICE: 200,
+    },
+    ENV: {
+        CLIENT_ID_KEYS: ['M365_CLIENT_ID', 'm365ClientId', 'MS365_MCP_CLIENT_ID'],
+        TENANT_ID_KEYS: ['M365_TENANT_ID', 'm365TenantId', 'MS365_MCP_TENANT_ID'],
+        GRAPH_BASE_URL_KEYS: ['M365_GRAPH_BASE_URL', 'm365GraphBaseUrl'],
+        TOKEN_CACHE_PATH_KEYS: ['M365_TOKEN_CACHE_PATH', 'm365TokenCachePath'],
+    },
+    TOOLS: {
+        WHOAMI: {
+            NAME: 'whoami',
+            DESCRIPTION: 'Show the signed-in Microsoft 365 user profile (display name, email, job title).',
+            FAILURE: 'whoami failed',
+        },
+        LIST_INBOX: {
+            NAME: 'list_inbox',
+            DESCRIPTION: 'List recent emails from the signed-in user inbox. Optionally filter unread only.',
+            TOP_DESCRIPTION: 'Maximum messages to return (1-50). Default 25.',
+            UNREAD_ONLY_DESCRIPTION: 'If true, return only unread messages.',
+            FAILURE: 'list_inbox failed',
+            EMPTY: 'No messages found.',
+        },
+        READ_EMAIL: {
+            NAME: 'read_email',
+            DESCRIPTION: 'Read a single email by message ID (from list_inbox).',
+            MESSAGE_ID_DESCRIPTION: 'Graph message ID.',
+            FAILURE: 'read_email failed',
+        },
+        SEND_EMAIL: {
+            NAME: 'send_email',
+            DESCRIPTION: 'Send an email from the signed-in user mailbox.',
+            TO_DESCRIPTION: 'Recipient email address.',
+            SUBJECT_DESCRIPTION: 'Email subject.',
+            BODY_DESCRIPTION: 'Plain-text email body.',
+            FAILURE: 'send_email failed',
+            SUCCESS: 'Email sent successfully.',
+        },
+        LIST_CALENDAR: {
+            NAME: 'list_calendar',
+            DESCRIPTION: 'List calendar events for a date range (defaults to today).',
+            START_DESCRIPTION: 'Start datetime ISO 8601, e.g. 2026-07-03T00:00:00.',
+            END_DESCRIPTION: 'End datetime ISO 8601, e.g. 2026-07-03T23:59:59.',
+            TOP_DESCRIPTION: 'Maximum events to return (1-50). Default 25.',
+            FAILURE: 'list_calendar failed',
+            EMPTY: 'No events found.',
+        },
+        LIST_TEAMS: {
+            NAME: 'list_teams',
+            DESCRIPTION: 'List Microsoft Teams the signed-in user has joined.',
+            FAILURE: 'list_teams failed',
+            EMPTY: 'No teams found.',
+        },
+        LIST_TEAMS_CHATS: {
+            NAME: 'list_teams_chats',
+            DESCRIPTION: 'List Teams chats (1:1 and group) for the signed-in user.',
+            TOP_DESCRIPTION: 'Maximum chats to return (1-50). Default 25.',
+            FAILURE: 'list_teams_chats failed',
+            EMPTY: 'No chats found.',
+        },
+        SEND_TEAMS_CHAT: {
+            NAME: 'send_teams_chat',
+            DESCRIPTION: 'Send a message to a Teams chat by chat ID (from list_teams_chats).',
+            CHAT_ID_DESCRIPTION: 'Teams chat ID.',
+            MESSAGE_DESCRIPTION: 'Plain-text message content.',
+            FAILURE: 'send_teams_chat failed',
+            SUCCESS: 'Chat message sent.',
+        },
+        LIST_CHANNELS: {
+            NAME: 'list_channels',
+            DESCRIPTION: 'List channels in a Microsoft Team by team ID (from list_teams).',
+            TEAM_ID_DESCRIPTION: 'Microsoft Team ID.',
+            FAILURE: 'list_channels failed',
+            EMPTY: 'No channels found.',
+        },
+        SEND_CHANNEL_MESSAGE: {
+            NAME: 'send_channel_message',
+            DESCRIPTION: 'Post a message to a Teams channel.',
+            TEAM_ID_DESCRIPTION: 'Microsoft Team ID.',
+            CHANNEL_ID_DESCRIPTION: 'Channel ID (from list_channels).',
+            MESSAGE_DESCRIPTION: 'Plain-text message content.',
+            FAILURE: 'send_channel_message failed',
+            SUCCESS: 'Channel message posted.',
+        },
+    },
+    MESSAGES: {
+        MISSING_CLIENT_ID: 'Missing M365_CLIENT_ID. Register an Azure app and set the client ID in MCP env or .env.',
+        MISSING_TENANT_ID: 'Missing M365_TENANT_ID. Set your Azure tenant ID in MCP env or .env.',
+        GENERIC_ERROR_PREFIX: 'Error:',
+        GRAPH_FAILED: 'Graph API request failed:',
+        NETWORK_ERROR: 'Network error calling Graph API:',
+        NOT_AUTHENTICATED: 'Not authenticated. Run `npm run login` in the m365-mcp folder or trigger any tool to sign in via device code.',
+    },
+};

package/dist/env.js

@@ -0,0 +1,26 @@
+import dotenv from 'dotenv';
+import { M365 } from './config/m365.config.js';
+dotenv.config();
+function readEnv(keys) {
+    for (const key of keys) {
+        const value = process.env[key];
+        if (value?.trim()) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+export const env = {
+    CLIENT_ID: readEnv(M365.ENV.CLIENT_ID_KEYS) ?? '',
+    TENANT_ID: readEnv(M365.ENV.TENANT_ID_KEYS) ?? '',
+    GRAPH_BASE_URL: readEnv(M365.ENV.GRAPH_BASE_URL_KEYS) ?? M365.GRAPH.DEFAULT_BASE_URL,
+    TOKEN_CACHE_PATH: readEnv(M365.ENV.TOKEN_CACHE_PATH_KEYS) ?? '',
+};
+export function validateEnv() {
+    if (!env.CLIENT_ID) {
+        throw new Error(M365.MESSAGES.MISSING_CLIENT_ID);
+    }
+    if (!env.TENANT_ID) {
+        throw new Error(M365.MESSAGES.MISSING_TENANT_ID);
+    }
+}

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { M365 } from './config/m365.config.js';
+import { validateEnv } from './env.js';
+import { registerTools } from './tools/index.js';
+validateEnv();
+const server = new McpServer({
+    name: M365.SERVER.NAME,
+    version: M365.SERVER.VERSION,
+});
+registerTools(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(M365.SERVER.STARTUP_MESSAGE);
+}
+main().catch((error) => {
+    console.error(M365.SERVER.FATAL_PREFIX, error);
+    process.exit(1);
+});

package/dist/interfaces/graph.js

@@ -0,0 +1 @@
+export {};

package/dist/scripts/login.js

@@ -0,0 +1,14 @@
+import { validateEnv } from '../env.js';
+import { getAccessToken } from '../services/authService.js';
+import { getMe } from '../services/graphService.js';
+validateEnv();
+async function main() {
+    await getAccessToken();
+    const user = await getMe();
+    console.log('Signed in successfully.');
+    console.log(`User: ${user.displayName ?? user.userPrincipalName ?? user.id}`);
+}
+main().catch((error) => {
+    console.error('Login failed:', error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/services/authService.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { PublicClientApplication } from '@azure/msal-node';
+import { M365 } from '../config/m365.config.js';
+import { env } from '../env.js';
+let pca;
+let authInProgress;
+export function getTokenCachePath() {
+    if (env.TOKEN_CACHE_PATH) {
+        return env.TOKEN_CACHE_PATH;
+    }
+    return path.join(os.homedir(), M365.CACHE.DEFAULT_DIR, M365.CACHE.DEFAULT_FILE);
+}
+function createCachePlugin(cachePath) {
+    return {
+        beforeCacheAccess: async (cacheContext) => {
+            if (fs.existsSync(cachePath)) {
+                cacheContext.tokenCache.deserialize(fs.readFileSync(cachePath, 'utf8'));
+            }
+        },
+        afterCacheAccess: async (cacheContext) => {
+            if (cacheContext.cacheHasChanged) {
+                fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+                fs.writeFileSync(cachePath, cacheContext.tokenCache.serialize());
+            }
+        },
+    };
+}
+function getClient() {
+    if (!pca) {
+        pca = new PublicClientApplication({
+            auth: {
+                clientId: env.CLIENT_ID,
+                authority: M365.GRAPH.AUTHORITY_TEMPLATE.replace('{tenant}', env.TENANT_ID),
+            },
+            cache: { cachePlugin: createCachePlugin(getTokenCachePath()) },
+        });
+    }
+    return pca;
+}
+export async function getAccessToken() {
+    if (authInProgress) {
+        return authInProgress;
+    }
+    authInProgress = acquireAccessToken();
+    try {
+        return await authInProgress;
+    }
+    finally {
+        authInProgress = undefined;
+    }
+}
+async function acquireAccessToken() {
+    const client = getClient();
+    const accounts = await client.getTokenCache().getAllAccounts();
+    if (accounts.length > 0) {
+        try {
+            const silent = await client.acquireTokenSilent({
+                scopes: [...M365.GRAPH.SCOPES],
+                account: accounts[0],
+            });
+            if (silent?.accessToken) {
+                return silent.accessToken;
+            }
+        }
+        catch {
+            // Device code login required.
+        }
+    }
+    const device = await client.acquireTokenByDeviceCode({
+        deviceCodeCallback: (response) => {
+            console.error(`\n${response.message}\n`);
+        },
+        scopes: [...M365.GRAPH.SCOPES],
+    });
+    if (!device?.accessToken) {
+        throw new Error(M365.MESSAGES.NOT_AUTHENTICATED);
+    }
+    return device.accessToken;
+}

package/dist/services/graphClient.js

@@ -0,0 +1,48 @@
+import { M365 } from '../config/m365.config.js';
+import { env } from '../env.js';
+import { getAccessToken } from './authService.js';
+function buildUrl(resourcePath, query) {
+    const base = resourcePath.startsWith('http')
+        ? resourcePath
+        : `${env.GRAPH_BASE_URL.replace(/\/$/, '')}/${resourcePath.replace(/^\//, '')}`;
+    const url = new URL(base);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+    }
+    return url.toString();
+}
+export function isSuccessStatus(status) {
+    return status >= M365.HTTP.SUCCESS_MIN && status <= M365.HTTP.SUCCESS_MAX;
+}
+export async function graphFetch(resourcePath, options = {}) {
+    const token = await getAccessToken();
+    const url = buildUrl(resourcePath, options.query);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: options.method ?? 'GET',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+                ...(options.body ? { 'Content-Type': 'application/json' } : {}),
+            },
+            body: options.body ? JSON.stringify(options.body) : undefined,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${M365.MESSAGES.NETWORK_ERROR} ${message}`);
+    }
+    if (!isSuccessStatus(response.status)) {
+        const body = (await response.text()).slice(0, M365.HTTP.ERROR_BODY_SLICE);
+        throw new Error(`${M365.MESSAGES.GRAPH_FAILED} HTTP ${response.status} ${body}`);
+    }
+    if (response.status === 204) {
+        return undefined;
+    }
+    return (await response.json());
+}

package/dist/services/graphService.js

@@ -0,0 +1,71 @@
+import { graphFetch } from './graphClient.js';
+export async function getMe() {
+    return graphFetch('/me');
+}
+export async function listInboxMessages(top, unreadOnly) {
+    const filter = unreadOnly ? 'isRead eq false' : undefined;
+    return graphFetch('/me/messages', {
+        query: {
+            $top: top,
+            $orderby: 'receivedDateTime desc',
+            $select: 'id,subject,bodyPreview,isRead,receivedDateTime,from',
+            ...(filter ? { $filter: filter } : {}),
+        },
+    });
+}
+export async function getMessage(messageId) {
+    return graphFetch(`/me/messages/${messageId}`, {
+        query: { $select: 'id,subject,bodyPreview,isRead,receivedDateTime,from,body' },
+    });
+}
+export async function sendMail(to, subject, body) {
+    await graphFetch('/me/sendMail', {
+        method: 'POST',
+        body: {
+            message: {
+                subject,
+                body: { contentType: 'Text', content: body },
+                toRecipients: [{ emailAddress: { address: to } }],
+            },
+            saveToSentItems: true,
+        },
+    });
+}
+export async function listCalendarEvents(start, end, top) {
+    return graphFetch('/me/calendarView', {
+        query: {
+            startDateTime: start,
+            endDateTime: end,
+            $top: top,
+            $orderby: 'start/dateTime',
+            $select: 'id,subject,start,end,location,organizer,isOnlineMeeting,onlineMeetingUrl',
+        },
+    });
+}
+export async function listJoinedTeams() {
+    return graphFetch('/me/joinedTeams');
+}
+export async function listChats(top) {
+    return graphFetch('/me/chats', {
+        query: { $top: top },
+    });
+}
+export async function sendChatMessage(chatId, content) {
+    await graphFetch(`/chats/${chatId}/messages`, {
+        method: 'POST',
+        body: {
+            body: { contentType: 'text', content },
+        },
+    });
+}
+export async function listTeamChannels(teamId) {
+    return graphFetch(`/teams/${teamId}/channels`);
+}
+export async function sendChannelMessage(teamId, channelId, content) {
+    await graphFetch(`/teams/${teamId}/channels/${channelId}/messages`, {
+        method: 'POST',
+        body: {
+            body: { contentType: 'text', content },
+        },
+    });
+}

package/dist/tools/index.js

@@ -0,0 +1,22 @@
+import { registerListCalendarTool } from './listCalendarTool.js';
+import { registerListChannelsTool } from './listChannelsTool.js';
+import { registerListInboxTool } from './listInboxTool.js';
+import { registerListTeamsChatsTool } from './listTeamsChatsTool.js';
+import { registerListTeamsTool } from './listTeamsTool.js';
+import { registerReadEmailTool } from './readEmailTool.js';
+import { registerSendChannelMessageTool } from './sendChannelMessageTool.js';
+import { registerSendEmailTool } from './sendEmailTool.js';
+import { registerSendTeamsChatTool } from './sendTeamsChatTool.js';
+import { registerWhoamiTool } from './whoamiTool.js';
+export function registerTools(server) {
+    registerWhoamiTool(server);
+    registerListInboxTool(server);
+    registerReadEmailTool(server);
+    registerSendEmailTool(server);
+    registerListCalendarTool(server);
+    registerListTeamsTool(server);
+    registerListTeamsChatsTool(server);
+    registerSendTeamsChatTool(server);
+    registerListChannelsTool(server);
+    registerSendChannelMessageTool(server);
+}

package/dist/tools/listCalendarTool.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { M365 } from '../config/m365.config.js';
+import { listCalendarEvents } from '../services/graphService.js';
+import { clampTop, formatError, todayRangeIso } from '../utils/format.js';
+export function registerListCalendarTool(server) {
+    const cfg = M365.TOOLS.LIST_CALENDAR;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, {
+        start: z.string().optional().describe(cfg.START_DESCRIPTION),
+        end: z.string().optional().describe(cfg.END_DESCRIPTION),
+        top: z.number().int().positive().max(M365.LIMITS.MAX_TOP).optional().describe(cfg.TOP_DESCRIPTION),
+    }, async ({ start, end, top }) => {
+        try {
+            const range = todayRangeIso();
+            const result = await listCalendarEvents(start ?? range.start, end ?? range.end, clampTop(top));
+            if (!result.value.length) {
+                return { content: [{ type: 'text', text: cfg.EMPTY }] };
+            }
+            const lines = result.value.map((event, index) => {
+                const location = event.location?.displayName ?? '(no location)';
+                return `${index + 1}. ${event.subject ?? '(no subject)'}\n   start: ${event.start?.dateTime ?? '?'} ${event.start?.timeZone ?? ''}\n   end: ${event.end?.dateTime ?? '?'}\n   location: ${location}`;
+            });
+            return { content: [{ type: 'text', text: `${result.value.length} event(s):\n\n${lines.join('\n\n')}` }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: formatError(error, cfg.FAILURE) }] };
+        }
+    });
+}

package/dist/tools/listChannelsTool.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { M365 } from '../config/m365.config.js';
+import { listTeamChannels } from '../services/graphService.js';
+import { formatError } from '../utils/format.js';
+export function registerListChannelsTool(server) {
+    const cfg = M365.TOOLS.LIST_CHANNELS;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, { teamId: z.string().min(1).describe(cfg.TEAM_ID_DESCRIPTION) }, async ({ teamId }) => {
+        try {
+            const result = await listTeamChannels(teamId);
+            if (!result.value.length) {
+                return { content: [{ type: 'text', text: cfg.EMPTY }] };
+            }
+            const lines = result.value.map((channel, index) => `${index + 1}. ${channel.displayName ?? '(unnamed)'}\n   id: ${channel.id}\n   membership: ${channel.membershipType ?? '?'}`);
+            return { content: [{ type: 'text', text: `${result.value.length} channel(s):\n\n${lines.join('\n\n')}` }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: formatError(error, cfg.FAILURE) }] };
+        }
+    });
+}

package/dist/tools/listInboxTool.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { M365 } from '../config/m365.config.js';
+import { listInboxMessages } from '../services/graphService.js';
+import { clampTop, formatError } from '../utils/format.js';
+export function registerListInboxTool(server) {
+    const cfg = M365.TOOLS.LIST_INBOX;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, {
+        top: z.number().int().positive().max(M365.LIMITS.MAX_TOP).optional().describe(cfg.TOP_DESCRIPTION),
+        unreadOnly: z.boolean().optional().describe(cfg.UNREAD_ONLY_DESCRIPTION),
+    }, async ({ top, unreadOnly }) => {
+        try {
+            const result = await listInboxMessages(clampTop(top), unreadOnly ?? false);
+            if (!result.value.length) {
+                return { content: [{ type: 'text', text: cfg.EMPTY }] };
+            }
+            const lines = result.value.map((msg, index) => {
+                const from = msg.from?.emailAddress?.address ?? '(unknown sender)';
+                const subject = (msg.subject ?? '(no subject)').slice(0, M365.LIMITS.SUBJECT_SLICE);
+                const read = msg.isRead ? 'read' : 'unread';
+                return `${index + 1}. [${read}] id=${msg.id}\n   from: ${from}\n   subject: ${subject}\n   received: ${msg.receivedDateTime ?? '?'}\n   preview: ${(msg.bodyPreview ?? '').slice(0, M365.LIMITS.PREVIEW_SLICE)}`;
+            });
+            return { content: [{ type: 'text', text: `${result.value.length} message(s):\n\n${lines.join('\n\n')}` }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: formatError(error, cfg.FAILURE) }] };
+        }
+    });
+}

package/dist/tools/listTeamsChatsTool.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { M365 } from '../config/m365.config.js';
+import { listChats } from '../services/graphService.js';
+import { clampTop, formatError } from '../utils/format.js';
+export function registerListTeamsChatsTool(server) {
+    const cfg = M365.TOOLS.LIST_TEAMS_CHATS;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, { top: z.number().int().positive().max(M365.LIMITS.MAX_TOP).optional().describe(cfg.TOP_DESCRIPTION) }, async ({ top }) => {
+        try {
+            const result = await listChats(clampTop(top));
+            if (!result.value.length) {
+                return { content: [{ type: 'text', text: cfg.EMPTY }] };
+            }
+            const lines = result.value.map((chat, index) => `${index + 1}. ${chat.topic ?? '(no topic)'}\n   id: ${chat.id}\n   type: ${chat.chatType ?? '?'}\n   updated: ${chat.lastUpdatedDateTime ?? '?'}`);
+            return { content: [{ type: 'text', text: `${result.value.length} chat(s):\n\n${lines.join('\n\n')}` }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: formatError(error, cfg.FAILURE) }] };
+        }
+    });
+}

package/dist/tools/listTeamsTool.js

@@ -0,0 +1,19 @@
+import { M365 } from '../config/m365.config.js';
+import { listJoinedTeams } from '../services/graphService.js';
+import { formatError } from '../utils/format.js';
+export function registerListTeamsTool(server) {
+    const cfg = M365.TOOLS.LIST_TEAMS;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, {}, async () => {
+        try {
+            const result = await listJoinedTeams();
+            if (!result.value.length) {
+                return { content: [{ type: 'text', text: cfg.EMPTY }] };
+            }
+            const lines = result.value.map((team, index) => `${index + 1}. ${team.displayName ?? '(unnamed)'}\n   id: ${team.id}\n   description: ${team.description ?? '(none)'}`);
+            return { content: [{ type: 'text', text: `${result.value.length} team(s):\n\n${lines.join('\n\n')}` }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: formatError(error, cfg.FAILURE) }] };
+        }
+    });
+}

package/dist/tools/readEmailTool.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { M365 } from '../config/m365.config.js';
+import { getMessage } from '../services/graphService.js';
+import { formatError } from '../utils/format.js';
+export function registerReadEmailTool(server) {
+    const cfg = M365.TOOLS.READ_EMAIL;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, { messageId: z.string().min(1).describe(cfg.MESSAGE_ID_DESCRIPTION) }, async ({ messageId }) => {
+        try {
+            const msg = await getMessage(messageId);
+            const from = msg.from?.emailAddress?.address ?? '(unknown sender)';
+            const body = msg.body?.content ?? msg.bodyPreview ?? '(no body)';
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            `id: ${msg.id}`,
+                            `from: ${from}`,
+                            `subject: ${msg.subject ?? '(no subject)'}`,
+                            `received: ${msg.receivedDateTime ?? '?'}`,
+                            `isRead: ${msg.isRead ?? false}`,
+                            '',
+                            '--- body ---',
+                            body,
+                        ].join('\n'),
+                    }],
+            };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: formatError(error, cfg.FAILURE) }] };
+        }
+    });
+}

package/dist/tools/sendChannelMessageTool.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { M365 } from '../config/m365.config.js';
+import { sendChannelMessage } from '../services/graphService.js';
+import { formatError } from '../utils/format.js';
+export function registerSendChannelMessageTool(server) {
+    const cfg = M365.TOOLS.SEND_CHANNEL_MESSAGE;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, {
+        teamId: z.string().min(1).describe(cfg.TEAM_ID_DESCRIPTION),
+        channelId: z.string().min(1).describe(cfg.CHANNEL_ID_DESCRIPTION),
+        message: z.string().min(1).describe(cfg.MESSAGE_DESCRIPTION),
+    }, async ({ teamId, channelId, message }) => {
+        try {
+            await sendChannelMessage(teamId, channelId, message);
+            return { content: [{ type: 'text', text: `${cfg.SUCCESS}\nTeam: ${teamId}\nChannel: ${channelId}` }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: formatError(error, cfg.FAILURE) }] };
+        }
+    });
+}

package/dist/tools/sendEmailTool.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { M365 } from '../config/m365.config.js';
+import { sendMail } from '../services/graphService.js';
+import { formatError } from '../utils/format.js';
+export function registerSendEmailTool(server) {
+    const cfg = M365.TOOLS.SEND_EMAIL;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, {
+        to: z.string().email().describe(cfg.TO_DESCRIPTION),
+        subject: z.string().min(1).describe(cfg.SUBJECT_DESCRIPTION),
+        body: z.string().min(1).describe(cfg.BODY_DESCRIPTION),
+    }, async ({ to, subject, body }) => {
+        try {
+            await sendMail(to, subject, body);
+            return { content: [{ type: 'text', text: `${cfg.SUCCESS}\nTo: ${to}\nSubject: ${subject}` }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: formatError(error, cfg.FAILURE) }] };
+        }
+    });
+}

package/dist/tools/sendTeamsChatTool.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import { M365 } from '../config/m365.config.js';
+import { sendChatMessage } from '../services/graphService.js';
+import { formatError } from '../utils/format.js';
+export function registerSendTeamsChatTool(server) {
+    const cfg = M365.TOOLS.SEND_TEAMS_CHAT;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, {
+        chatId: z.string().min(1).describe(cfg.CHAT_ID_DESCRIPTION),
+        message: z.string().min(1).describe(cfg.MESSAGE_DESCRIPTION),
+    }, async ({ chatId, message }) => {
+        try {
+            await sendChatMessage(chatId, message);
+            return { content: [{ type: 'text', text: `${cfg.SUCCESS}\nChat: ${chatId}` }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: formatError(error, cfg.FAILURE) }] };
+        }
+    });
+}

package/dist/tools/whoamiTool.js

@@ -0,0 +1,26 @@
+import { M365 } from '../config/m365.config.js';
+import { getMe } from '../services/graphService.js';
+import { formatError } from '../utils/format.js';
+export function registerWhoamiTool(server) {
+    const cfg = M365.TOOLS.WHOAMI;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, {}, async () => {
+        try {
+            const user = await getMe();
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            'Signed-in Microsoft 365 user:',
+                            `- id: ${user.id}`,
+                            `- displayName: ${user.displayName ?? '(unknown)'}`,
+                            `- email: ${user.mail ?? user.userPrincipalName ?? '(unknown)'}`,
+                            `- jobTitle: ${user.jobTitle ?? '(not set)'}`,
+                        ].join('\n'),
+                    }],
+            };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: formatError(error, cfg.FAILURE) }] };
+        }
+    });
+}

package/dist/utils/format.js

@@ -0,0 +1,17 @@
+import { M365 } from '../config/m365.config.js';
+export function clampTop(top) {
+    const value = top ?? M365.LIMITS.DEFAULT_TOP;
+    return Math.min(Math.max(1, value), M365.LIMITS.MAX_TOP);
+}
+export function formatError(error, fallback) {
+    const message = error instanceof Error ? error.message : fallback;
+    return `${M365.MESSAGES.GENERIC_ERROR_PREFIX} ${message}`;
+}
+export function todayRangeIso() {
+    const now = new Date();
+    const start = new Date(now);
+    start.setHours(0, 0, 0, 0);
+    const end = new Date(now);
+    end.setHours(23, 59, 59, 999);
+    return { start: start.toISOString(), end: end.toISOString() };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@mhdd_24/m365-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Microsoft Outlook and Teams via Microsoft Graph API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "m365-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "prepack": "npm run build",
+    "start": "node dist/index.js",
+    "login": "tsx src/scripts/login.ts"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "microsoft-365",
+    "outlook",
+    "teams",
+    "graph-api",
+    "cursor"
+  ],
+  "author": "Mhdd-24",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mhdd-24/M365-MCP.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Mhdd-24/M365-MCP/issues"
+  },
+  "homepage": "https://github.com/Mhdd-24/M365-MCP#readme",
+  "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@azure/msal-node": "^3.8.4",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}