OfficeMCP

Remote MCP server for Microsoft Graph with delegated OAuth support.

Quick start

1. Copy .env.example to .env.
2. Install dependencies with npm install.
3. Run npm run dev.
4. The MCP endpoint is http://localhost:3000/mcp.
5. For a container path, build with docker build -t office-mcp ..

Auth modes

• AUTH_ENABLED=false: local development without bearer-token enforcement.
• AUTH_ENABLED=true with GRAPH_TOKEN_MODE=passthrough: validates bearer tokens and forwards the same user token to Microsoft Graph.
• AUTH_ENABLED=true with GRAPH_TOKEN_MODE=obo: validates bearer tokens for this MCP resource and exchanges them for a Microsoft Graph delegated token via on-behalf-of flow.

Notes

• Streamable HTTP is used for the remote MCP transport.
• OAuth Protected Resource Metadata is exposed when auth is enabled.
• File-oriented tools cap direct content extraction at MAX_FILE_SIZE_BYTES and default to 5 MB, matching current Work IQ preview guidance for some file operations.
• /diagnostics/auth provides a non-secret snapshot of auth and token-mode configuration for setup troubleshooting.
• The local test suite now covers both unauthenticated and authenticated MCP route behavior with a mocked verified bearer token.

Current tool coverage

• user profile and organization context
• direct reports
• mail list, get, search, draft, reply, and send
• calendar list, get, create, update, delete, and schedule lookup
• OneDrive search, recent items, item metadata, folder children, and folder creation
• SharePoint site search, site lookup, document libraries, lists, and list items
• Teams joined teams, chats, channels, channel messages, and chat messages
• Word document text extraction
• cross-M365 retrieval via Microsoft Graph search

Additional docs

• Architecture
• Deployment
• Entra setup
• Auth runbook
• Permissions matrix
• Tool catalog
• Live verification

Smoke testing

With the server running locally:

npm run smoke

The default smoke tool is server_get_status, so local MCP verification works even without Microsoft Graph credentials.

For auth-enabled setup, use .env.auth.example as the starting template.

To call a specific tool:

SMOKE_TOOL=mail_list_messages SMOKE_TOOL_ARGS='{"top":5}' npm run smoke

To exercise bearer-protected mode, set SMOKE_BEARER_TOKEN in the environment before running the smoke script.

To inspect a token's audience, scopes, tenant, and expiry without sending it anywhere:

npm run inspect-token -- "<jwt>"

Diagnostics

For setup troubleshooting:

curl http://localhost:3000/diagnostics/auth

This endpoint includes non-secret warnings for common misconfigurations such as:

• auth disabled
• missing resource audience
• incomplete OBO configuration
• wildcard CORS in production-like setups

When auth is enabled, the MCP server also exposes protected resource metadata at:

curl http://localhost:3000/.well-known/oauth-protected-resource/mcp

To quickly inspect all readiness endpoints together:

npm run live-readiness

When AUTH_ENABLED=false, the auth metadata endpoints will correctly return 404.