microsoft-outlook-mcp

每个服务都使用真正的 MCP 协议，并支持任一种传输方式：

• stdio — 供本地 MCP 客户端使用，由客户端将服务作为子进程启动（Claude Desktop、IDE、MCP Inspector）。
• Streamable HTTP — 供远程/托管场景使用，通过 Authorization: Bearer 在每次请求中提供 Microsoft Graph 访问令牌。

服务

	服务	npm 包（及二进制文件）	工具
	日历	ms-calendar-mcp	9
	联系人	ms-contacts-mcp	7
	OneDrive	ms-onedrive-mcp	9
	Outlook	microsoft-outlook-mcp	14
	SharePoint	ms-sharepoint-mcp	23

所有工具都是对 Microsoft Graph v1.0 API 的轻量封装。

目录结构

microsoft-mcp/
├── apps/                       # one MCP server per Microsoft 365 product
│   ├── calendar/
│   ├── contacts/
│   ├── onedrive/
│   ├── outlook/
│   └── sharepoint/
│       └── src/
│           ├── tools.ts        # declarative tool definitions (schema + handler)
│           └── index.ts        # run({ name, version }, tools)
└── packages/                   # shared building blocks
    ├── core/                   # MCP server bootstrap + dual transport (stdio / HTTP)
    ├── graph/                  # Microsoft Graph HTTP client
    ├── validation/             # id / path / query sanitizers
    └── logger/                 # structured JSON logging (stderr-only — stdio-safe)

服务只需将工具列表传递给 run()：

// apps/calendar/src/index.ts
import { run } from "@microsoft-mcp/core";
import { tools } from "./tools.js";

void run({ name: "microsoft-calendar", version: "1.0.0", title: "Microsoft Calendar" }, tools);

// a single tool
defineTool({
  name: "get_event",
  description: "Get a single calendar event by ID.",
  inputSchema: { event_id: z.string().describe("Event ID") },
  confirmationPolicy: "never",
  handler: ({ graph }, { event_id }) => {
    validateId(event_id, "event_id");
    return graph.request("GET", `/me/events/${event_id}`);
  },
});

confirmationPolicy（对会修改或破坏数据的工具设为 "always"，对只读工具设为 "never"）会作为 MCP readOnlyHint / destructiveHint 注解提供给客户端。

要求

• Node.js >= 20
• pnpm 10（corepack enable）

设置

pnpm install
pnpm build        # build all servers (turbo) -> apps/*/dist/index.js
pnpm check-types  # typecheck everything

测试与 CI

pnpm test            # run the vitest suite once
pnpm test:watch      # watch mode
pnpm test:coverage   # run with a v8 coverage report (-> coverage/)

测试与代码放在一起，文件名为 *.test.ts，直接对 TypeScript 源码运行（无需构建步骤）。共享的 packages/* 均通过单元测试和集成测试进行覆盖，其中包括针对运行中服务进行的完整 Streamable-HTTP 往返测试；CI 会强制执行最低覆盖率要求。每个 apps/* 服务都包含一套不变量测试，用于锁定其工具接口（名称唯一且采用 snake_case、架构有效、确认策略有效）。

每次向 master 推送或提交拉取请求时，都会运行 CI：类型检查 → 构建 → 覆盖率测试。覆盖率徽章会根据运行结果重新生成。

身份验证

使用 Microsoft 帐户登录一次后，服务会缓存刷新令牌，并在此后静默获取访问令牌——无需粘贴令牌，也不会遇到 1 小时过期的问题。登录使用你自己的 Microsoft Entra ID 应用注册（免费），因此这些服务会以你的名义执行操作。

1. 注册 Entra ID 应用（仅需一次）

1. Azure Portal → Microsoft Entra ID → App registrations → New registration。名称不限；选择适合的 Supported account types（单租户、多租户和/或个人帐户）。

2. Authentication → Add a platform → Mobile and desktop applications → 添加重定向 URI http://localhost，并将 Allow public client flows 设置为 Yes（启用 --device-code 回退方式）。

3. API permissions → Add a permission → Microsoft Graph → Delegated permissions → 添加所用服务所需的作用域（如果租户要求，请执行 Grant admin consent）：

   服务	委托作用域
   Calendar	Calendars.ReadWrite
   Contacts	Contacts.ReadWrite
   OneDrive	Files.ReadWrite.All
   Outlook	Mail.ReadWrite、Mail.Send
   SharePoint	Sites.ReadWrite.All

   所有服务也会使用 User.Read。（会自动请求 offline_access 以便刷新。）

4. 复制 Application (client) ID。

2. 登录（每台机器仅需一次）

设置 MICROSOFT_CLIENT_ID，然后运行服务的 login 命令。浏览器会打开；同意后，令牌会缓存在 ~/.config/microsoft-mcp/ 下：

export MICROSOFT_CLIENT_ID=<your-client-id>

npx -y ms-calendar-mcp login           # opens the browser
npx -y ms-calendar-mcp login --device-code   # headless: shows a code to enter

之后，服务会自动刷新令牌。使用 MICROSOFT_TENANT_ID 指定非默认租户（默认值为 common）。

高级用法：提供自己的令牌

若要绕过内置流程，可直接提供预先获取的 Graph 令牌：

• **stdio：**设置 MICROSOFT_ACCESS_TOKEN（优先于缓存的登录凭据）。适合快速测试——使用 az account get-access-token --resource https://graph.microsoft.com --query accessToken -o tsv 创建令牌。
• **HTTP：**在每个 POST /mcp 请求中发送 Authorization: Bearer <token>。每个请求都是无状态的，并使用自己的令牌，因此调用方不会共享凭据——托管/远程部署采用此模式，并自行处理身份验证。

运行

stdio（例如 Claude Desktop）

每个服务都发布在 npm 上，可通过 npx 运行——无需克隆或构建。请先登录一次（npx -y ms-calendar-mcp login，参见身份验证），然后运行：

// claude_desktop_config.json
{
  "mcpServers": {
    "microsoft-calendar": {
      "command": "npx",
      "args": ["-y", "ms-calendar-mcp"],
      "env": { "MICROSOFT_CLIENT_ID": "<your-client-id>" }
    }
  }
}

或者使用本地构建版本，而非 npm：

{
  "command": "node",
  "args": ["/abs/path/microsoft-mcp/apps/calendar/dist/index.js"],
  "env": { "MICROSOFT_CLIENT_ID": "<your-client-id>" }
}

开发期间，可以跳过构建，直接运行 TypeScript：

MICROSOFT_ACCESS_TOKEN=<token> pnpm --filter ms-calendar-mcp dev

Streamable HTTP

# build first, then:
PORT=3000 node apps/calendar/dist/index.js --http
# or, in dev:
pnpm --filter ms-calendar-mcp dev -- --http --port 3000

服务提供 POST /mcp（MCP 端点）和 GET /healthz。将任何 Streamable-HTTP MCP 客户端指向 http://localhost:3000/mcp，并附带 Authorization: Bearer 标头。

传输方式选择

按以下顺序确定：--stdio / --http 标志 → MCP_TRANSPORT=stdio|http → 默认值 stdio。 HTTP 端口：--port <n> → PORT → 3000。

环境变量

变量	使用方	说明
MICROSOFT_CLIENT_ID	stdio	用于登录的 Entra ID 应用程序（客户端）ID。login 流程必需。
MICROSOFT_TENANT_ID	stdio	登录租户：common（默认值）、organizations、consumers 或租户 ID。
MICROSOFT_ACCESS_TOKEN	stdio	预先获取的 Graph 令牌；设置后会覆盖缓存的登录凭据。
MICROSOFT_MCP_CACHE_DIR	stdio	覆盖令牌缓存目录（默认值为 ~/.config/microsoft-mcp）。
MCP_TRANSPORT	两者	stdio（默认值）或 http。
PORT	http	监听端口（默认值为 3000）。
MCP_HTTP_BODY_LIMIT	http	Base64 上传的最大请求正文大小（默认值为 50mb）。
MCP_DEBUG	两者	设置任意非空值即可启用调试日志（输出到 stderr）。