# ryaker/outlook-mcp architecture

> Architecture diagram of the GitHub repository ryaker/outlook-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryaker/outlook-mcp
- Repository: https://github.com/ryaker/outlook-mcp

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Claude["Claude Desktop Client"]:::client

    %% Server Core
    subgraph "Server Core"
        MCP["MCP Server (HTTP :3333 & Tool Registry)"]:::server
        Config["Configuration (.env, config.js, claude-config)"]:::server
        OAuthServer["OAuth Callback Server"]:::server
    end

    %% Modules
    subgraph "Auth Module"
        AuthIndex["auth/index.js"]:::module
        TokenMgr["auth/token-manager.js"]:::module
        AuthTools["auth/tools.js"]:::module
    end

    subgraph "Calendar Module"
        CalIndex["calendar/index.js"]:::module
        CalList["calendar/list.js"]:::module
        CalCreate["calendar/create.js"]:::module
        CalDelete["calendar/delete.js"]:::module
        CalAccept["calendar/accept.js"]:::module
        CalDecline["calendar/decline.js"]:::module
        CalCancel["calendar/cancel.js"]:::module
    end

    subgraph "Email Module"
        EmailIndex["email/index.js"]:::module
        EmailList["email/list.js"]:::module
        EmailRead["email/read.js"]:::module
        EmailSearch["email/search.js"]:::module
        EmailSend["email/send.js"]:::module
    end

    subgraph "Folder Module"
        FIndex["folder/index.js"]:::module
        FList["folder/list.js"]:::module
        FCreate["folder/create.js"]:::module
        FMove["folder/move.js"]:::module
    end

    %% Utils Layer
    subgraph "Utils Layer"
        GraphAPI["utils/graph-api.js"]:::utils
        OData["utils/odata-helpers.js"]:::utils
        Mock["utils/mock-data.js"]:::utils
    end

    %% External Services
    subgraph "External Services"
        AzureAD["Azure AD / OAuth2"]:::external
        MSGraph["Microsoft Graph API"]:::external
    end

    %% Persistence
    TokenStore["Token Store (~/.outlook-mcp-tokens.json)"]:::persistence

    %% Connections
    Claude -->|"HTTP Request"| MCP
    Config --> MCP
    MCP -->|"Dispatch to Auth"| AuthIndex
    MCP -->|"Dispatch to Calendar"| CalIndex
    MCP -->|"Dispatch to Email"| EmailIndex
    MCP -->|"Dispatch to Folder"| FIndex

    AuthIndex --> TokenMgr
    AuthIndex --> AuthTools
    AuthIndex --> GraphAPI

    CalIndex --> GraphAPI
    CalList --> GraphAPI
    CalCreate --> GraphAPI
    CalDelete --> GraphAPI
    CalAccept --> GraphAPI
    CalDecline --> GraphAPI
    CalCancel --> GraphAPI

    EmailIndex --> GraphAPI
    EmailList --> GraphAPI
    EmailRead --> GraphAPI
    EmailSearch --> GraphAPI
    EmailSend --> GraphAPI

    FIndex --> GraphAPI
    FList --> GraphAPI
    FCreate --> GraphAPI
    FMove --> GraphAPI

    GraphAPI -->|"test-mode & mock"| Mock
    GraphAPI -->|"token check/refresh"| AzureAD
    GraphAPI -->|"OData Queries"| OData
    GraphAPI -->|"API Call"| MSGraph

    MSGraph -->|Response| GraphAPI

    AzureAD -->|OAuth Callback| OAuthServer
    OAuthServer -->|Token Data| TokenMgr
    TokenMgr -->|Persist| TokenStore

    %% Click Events
    click MCP "https://github.com/ryaker/outlook-mcp/blob/main/index.js"
    click Config "https://github.com/ryaker/outlook-mcp/blob/main/config.js"
    click Config "https://github.com/ryaker/outlook-mcp/blob/main/.env"
    click Config "https://github.com/ryaker/outlook-mcp/blob/main/claude-config-sample.json"
    click OAuthServer "https://github.com/ryaker/outlook-mcp/blob/main/outlook-auth-server.js"
    click AuthIndex "https://github.com/ryaker/outlook-mcp/blob/main/auth/index.js"
    click TokenMgr "https://github.com/ryaker/outlook-mcp/blob/main/auth/token-manager.js"
    click AuthTools "https://github.com/ryaker/outlook-mcp/blob/main/auth/tools.js"
    click CalIndex "https://github.com/ryaker/outlook-mcp/blob/main/calendar/index.js"
    click CalList "https://github.com/ryaker/outlook-mcp/blob/main/calendar/list.js"
    click CalCreate "https://github.com/ryaker/outlook-mcp/blob/main/calendar/create.js"
    click CalDelete "https://github.com/ryaker/outlook-mcp/blob/main/calendar/delete.js"
    click CalAccept "https://github.com/ryaker/outlook-mcp/blob/main/calendar/accept.js"
    click CalDecline "https://github.com/ryaker/outlook-mcp/blob/main/calendar/decline.js"
    click CalCancel "https://github.com/ryaker/outlook-mcp/blob/main/calendar/cancel.js"
    click EmailIndex "https://github.com/ryaker/outlook-mcp/blob/main/email/index.js"
    click EmailList "https://github.com/ryaker/outlook-mcp/blob/main/email/list.js"
    click EmailRead "https://github.com/ryaker/outlook-mcp/blob/main/email/read.js"
    click EmailSearch "https://github.com/ryaker/outlook-mcp/blob/main/email/search.js"
    click EmailSend "https://github.com/ryaker/outlook-mcp/blob/main/email/send.js"
    click FIndex "https://github.com/ryaker/outlook-mcp/blob/main/folder/index.js"
    click FList "https://github.com/ryaker/outlook-mcp/blob/main/folder/list.js"
    click FCreate "https://github.com/ryaker/outlook-mcp/blob/main/folder/create.js"
    click FMove "https://github.com/ryaker/outlook-mcp/blob/main/folder/move.js"
    click GraphAPI "https://github.com/ryaker/outlook-mcp/blob/main/utils/graph-api.js"
    click OData "https://github.com/ryaker/outlook-mcp/blob/main/utils/odata-helpers.js"
    click Mock "https://github.com/ryaker/outlook-mcp/blob/main/utils/mock-data.js"

    %% Styles
    classDef client fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef server fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef module fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef utils fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef external fill:#d6d8f9,stroke:#333,stroke-width:1px;
    classDef persistence fill:#e2e3e5,stroke:#333,stroke-width:1px;
```
