Ms Contacts MCP

Microsoft MCP

Model Context Protocol servers for Microsoft 365.

Calendar · Contacts · OneDrive · Outlook · SharePoint — on the official @modelcontextprotocol/sdk , over stdio or Streamable HTTP.

Each server speaks the real MCP protocol and runs over either transport:

• stdio — for local MCP clients that launch the server as a subprocess (Claude Desktop, IDEs, the MCP Inspector).
• Streamable HTTP — for remote/hosted use, with the Microsoft Graph access token supplied per request via Authorization: Bearer.

Servers

| | Server | npm package (and binary) | Tools | | :-: | ----------- | ------------------------- | ----: | | | Calendar | ms-calendar-mcp | 9 | | | Contacts | ms-contacts-mcp | 7 | | | OneDrive | ms-onedrive-mcp | 9 | | | Outlook | microsoft-outlook-mcp | 14 | | | SharePoint | ms-sharepoint-mcp | 23 |

All tools are thin wrappers over the Microsoft Graph v1.0 API.

Layout

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)

A server is just a list of tools handed to 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" for mutating/destructive tools, "never" for read-only) is surfaced to clients as MCP readOnlyHint / destructiveHint annotations.

Requirements

• Node.js >= 20
• pnpm 10 (corepack enable)

Setup

pnpm install

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

Tests & CI

pnpm test            # run the vitest suite once

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

Tests live next to the code as *.test.ts and run on TypeScript source directly (no build step). The shared packages/* are covered by unit and integration tests — including a full Streamable-HTTP round-trip against a live server — and CI enforces a coverage floor on them. Each apps/* server ships an invariant suite that locks its tool surface (unique snake_case names, valid schemas and confirmation policies).

Every push and pull request to master runs CI: typecheck → build → tests with coverage. The coverage badge is regenerated from the run.

Authentication

You sign in once with your Microsoft account; the server then caches a refresh token and acquires access tokens silently from then on — no pasting, no 1-hour expiry. Sign-in uses your own Microsoft Entra ID app registration (free) so the servers act on your behalf.

1. Register an Entra ID app (one time)

1. Azure Portal → Microsoft Entra ID → App registrations → New registration. Name it anything; pick the Supported account types that fit (single-tenant, multi-tenant, and/or personal accounts).
2. Authentication → Add a platform → Mobile and desktop applications → add redirect URI `http://localhost`, and set Allow public client flows to Yes (enables the --device-code fallback).
3. API permissions → Add a permission → Microsoft Graph → Delegated permissions → add the scopes for the servers you use (then Grant admin consent if your tenant requires it):

All servers also use User.Read. (offline_access is requested automatically for refresh.)

1. Copy the Application (client) ID.

2. Sign in (one time per machine)

Set MICROSOFT_CLIENT_ID, then run the server's `login` command. A browser opens; after you consent, the token is cached under ~/.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

From then on the server refreshes tokens automatically. Use a non-default tenant with MICROSOFT_TENANT_ID (default common).

Advanced: supply your own token

To bypass the built-in flow, supply a pre-acquired Graph token directly:

• stdio: set MICROSOFT_ACCESS_TOKEN (takes precedence over the cached sign-in). Good for quick tests — mint one with az account get-access-token --resource https://graph.microsoft.com --query accessToken -o tsv.
• HTTP: send Authorization: Bearer on each POST /mcp request. Each request is stateless with its own token, so callers never share credentials — this is the model for hosted/remote deployments, which handle their own auth.

Running

stdio (e.g. Claude Desktop)

Each server is published to npm and runnable with npx — no clone or build. Sign in once first (npx -y ms-calendar-mcp login, see Authentication), then:

// claude_desktop_config.json

{ "mcpServers": { "microsoft-calendar": { "command": "npx", "args": ["-y", "ms-calendar-mcp"], "env": { "MICROSOFT_CLIENT_ID": " " } } } }

Or point at a local build instead of npm:

{

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

During development you can skip the build and run the TypeScript directly:

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

The server exposes POST /mcp (the MCP endpoint) and GET /healthz. Point any Streamable-HTTP MCP client at http://localhost:3000/mcp with an Authorization: Bearer header.

Transport selection

Resolved in this order: --stdio / --http flag → MCP_TRANSPORT=stdio|http → default stdio. HTTP port: --port → PORT → 3000.

Environment variables