How ryaker/outlook-mcp works
Project Type and Purpose
• This is a Node.js–based modular MCP (Model Context Protocol) server that exposes Outlook functionality (email and calendar) to the Claude Desktop client using Microsoft Graph API.
• It functions as a backend “tool server” rather than a traditional full-stack web app.
File‐Structure Analysis
• Top‐level:
• index.js → Main server bootstrap, aggregates tools
• config.js → Server/global configuration
• .env/claude-config → Environment and Claude integration
• outlook-auth-server.js → Local HTTP server for OAuth callbacks
• test scripts & utilities
• Directories:
• auth/ → OAuth2 flow, token management
• calendar/ → Calendar operations (list/create/delete/accept/decline)
• email/ → Email operations (list/search/read/send)
• utils/ → Shared helpers (Graph API wrapper, OData, mock data)
Key README Insights
• No frontend UI; the “client” is Claude Desktop invoking tools via HTTP
• Authentication flow uses Azure AD (OAuth2) and stores tokens locally
• Modules register tool handlers in index.js and expose them over MCP
• Test mode via mock-data, test scripts
a. Main Components
1. Claude Desktop Client (MCP Consumer)
2. MCP Server (Node.js process)
– HTTP Listener (port 3333)
– Tool Registry (index.js → TOOLS array)
3. Module Layers:
• Auth Module (OAuth flow, token-manager, tools)
• Calendar Module (CRUD handlers)
• Email Module (CRUD handlers)
• Utils Layer (graph-api wrapper, OData helpers, mock-data)
4. External Services:
• Azure AD / OAuth2 Authorization Server
• Microsoft Graph API Endpoints
5. Local Persistence:
• Token store file (~/.outlook-mcp-tokens.json)
6. Configuration:
• .env, config.js, claude-config-sample.json
b. Relationships & Data Flows
• Claude → (HTTP request) → MCP Server → Tool Dispatcher
• Tool Dispatcher → Appropriate Module (email/calendar/auth)
• Module → Utils.graph-api →
• If test mode → mock-data
• Else → Azure AD (token refresh if needed) → Microsoft Graph
• Graph API response → Module → MCP Server → Claude response
• Outlook-auth-server: separate HTTP endpoint for OAuth callback → auth/token-manager → persist tokens
c. Architectural Patterns
• Modular “tool” pattern: Each feature lives in its directory with exports aggregated
• Layered architecture: Presentation (MCP protocol) → Business logic modules → Data access (Graph API wrapper) → External APIs
• Dependency inversion: Modules code against graph-api helper interface, mockable for tests
d. Key Technologies
• Node.js, Express (for auth server and MCP endpoint)
• Microsoft Graph API (via REST, wrapped in graph-api.js)
• OAuth2 (Azure AD)
• OData query generation
• JSON file store for tokens