o365-graph-connector

Microsoft 365 Graph Access Utility

A Model Context Protocol (MCP) server designed for interfacing with Microsoft 365 services, particularly through the Graph API interface.

Essential Prerequisites

• Node.js runtime environment, version 20 or newer (strongly advised)
• Node.js version 14 might function, though dependency warnings are anticipated

Core Capabilities

• Secure Authorization leveraging the Microsoft Authentication Library (MSAL)
• Deep integration across diverse Microsoft 365 platforms
• Option to operate strictly in a read-only operational mode for enhanced safety
• Fine-grained control over accessible functionalities via tool filtering mechanisms

Supported APIs & Modules

Personal Account Toolset (Default Access)

Electronic Mail (Outlook)
_{list-mail-messages, list-mail-folders, list-mail-folder-messages, get-mail-message, send-mail, delete-mail-message, create-draft-email, move-mail-message}

Scheduling (Calendar)
_{list-calendars, list-calendar-events, get-calendar-event, get-calendar-view, create-calendar-event, update-calendar-event, delete-calendar-event}

Cloud File Storage (OneDrive)
_{list-drives, get-drive-root-item, list-folder-files, download-onedrive-file-content, upload-file-content, upload-new-file, delete-onedrive-file}

Spreadsheet Operations (Excel)
_{list-excel-worksheets, get-excel-range, create-excel-chart, format-excel-range, sort-excel-range}

Note-Taking (OneNote)
_{list-onenote-notebooks, list-onenote-notebook-sections, list-onenote-section-pages, get-onenote-page-content, create-onenote-page}

Task Management (To Do)
_{list-todo-task-lists, list-todo-tasks, get-todo-task, create-todo-task, update-todo-task, delete-todo-task}

Project Management (Planner)
_{list-planner-tasks, get-planner-plan, list-plan-tasks, get-planner-task, create-planner-task}

Contact Directory
_{list-outlook-contacts, get-outlook-contact, create-outlook-contact, update-outlook-contact, delete-outlook-contact}

User Identity Information
_{get-current-user}

Information Retrieval
_search-query

Organization Account Toolset (Requires --org-mode activation)

Collaboration Hubs (Teams & Chats)
_{list-chats, get-chat, list-chat-messages, get-chat-message, send-chat-message, list-chat-message-replies, reply-to-chat-message, list-joined-teams, get-team, list-team-channels, get-team-channel, list-channel-messages, get-channel-message, send-channel-message, list-team-members}

Document Collaboration Sites (SharePoint)
_{search-sharepoint-sites, get-sharepoint-site, get-sharepoint-site-by-path, list-sharepoint-site-drives, get-sharepoint-site-drive-by-id, list-sharepoint-site-items, get-sharepoint-site-item, list-sharepoint-site-lists, get-sharepoint-site-list, list-sharepoint-site-list-items, get-sharepoint-site-list-item, get-sharepoint-sites-delta}

Delegated Mailboxes
_{list-shared-mailbox-messages, list-shared-mailbox-folder-messages, get-shared-mailbox-message, send-shared-mailbox-mail}

Identity Administration
_list-users

Organization/Work Access Configuration

To unlock enterprise/school features (such as Teams, SharePoint interactions), utilize the organization mode initiation flag:

{ "mcpServers": { "ms365": { "command": "npx", "args": ["-y", "@softeria/ms-365-mcp-server", "--org-mode"] } } }

Organization mode setting is mandatory upon server launch to gain access to corporate functionalities. Without it, only personal productivity suite access (email, calendar, OneDrive, etc.) is provisioned.

Shared Mailbox Operation

Accessing delegated mailboxes necessitates several prerequisites:

1. Organizational Context: Shared mailbox utilities mandate the --org-mode flag activation (restricted to work/school accounts).
2. Delegation Scopes: Required permissions include Mail.Read.Shared or Mail.Send.Shared OAuth scopes.
3. Exchange Authorization: The user initiating the action must have explicit delegate access granted to the target shared mailbox.
4. Invocation Method: Employ the shared mailbox's primary email address as the user-id argument within the relevant shared mailbox tools.

Discovering Shared Mailboxes: Run the list-users utility to enumerate accessible user identities and associated shared mailboxes within your tenant.

Example invocation: list-shared-mailbox-messages supplying shared-mailbox@company.com as the user-id parameter.

Initial Setup Example

Test interactive login within the Claude Desktop environment:

Operational Examples

Integration Procedures

Claude Desktop Integration

Modify the configuration file found under Settings > Developer:

{ "mcpServers": { "ms365": { "command": "npx", "args": ["-y", "@softeria/ms-365-mcp-server"] } } }

Claude Code CLI Addition

bash claude mcp add ms365 -- npx -y @softeria/ms-365-mcp-server

For other environments supporting MCP specifications, consult their specific documentation for the appropriate configuration method.

Local Development Setup

For direct local execution or debugging purposes:

bash

Execute from the root directory of the project

claude mcp add ms -- npx tsx src/index.ts --org-mode

Alternatively, manual configuration in Claude Desktop:

{ "mcpServers": { "ms365": { "command": "node", "args": ["/absolute/path/to/ms-365-mcp-server/dist/index.js", "--org-mode"] } } }

Maintenance Notice: After any source code modifications, execute npm run build to synchronize changes into the deployable dist/ directory.

Authentication Mechanisms

⚠️ Verification of credentials is a prerequisite for tool utilization.

The server supports three distinct methods for establishing authenticated sessions:

1. Device Code Flow (Default Protocol)

For interactive authorization initiation:

• MCP Client Invocation: Invoke the login operation (it automatically checks for existing valid tokens).
• If a prompt appears, acquire the displayed URL and verification code, then proceed to the browser.

• Conclude the process by using the verify-login operation.

• CLI Invocation: bash npx @softeria/ms-365-mcp-server --login

Follow the displayed URL and enter the provided code directly within the terminal interface.

Authentication tokens are persisted securely within the operating system's credential storage facility (with file system backup as a fallback).

2. OAuth Authorization Code Flow (HTTP Transport Required)

When the server is initiated using the --http parameter, OAuth authorization becomes mandatory:

bash npx @softeria/ms-365-mcp-server --http 3000

This mode accomplishes the following:

• Advertises comprehensive OAuth capabilities to connected MCP clients.
• Exposes OAuth endpoints at the /auth/* path (covering authorization, token exchange, and metadata retrieval).
• Mandates the presence of an Authorization: Bearer <token> header for every subsequent MCP request.
• Token validity is confirmed against the Microsoft Graph API endpoint.
• Standard login/logout operations are suppressed by default (enable them via --enable-auth-tools).

MCP clients equipped to handle OAuth flows will manage this process automatically upon detecting the advertised protocol support.

Establishing Azure AD Context for OAuth Testing

To employ OAuth mode utilizing custom credentials registered within your Azure tenant (recommended for production deployment contexts), an Azure AD application registration is required:

1. App Registration Creation:

2. Access the Azure Portal.

3. Navigate to Azure Active Directory → App registrations → Initiate a New registration.

4. Assign a suitable identifier, e.g., "MS365 MCP Server".

5. Redirect URI Configuration: Register the following URIs for compatibility testing with MCP Inspector (npm run inspector):

6. http://localhost:6274/oauth/callback

7. http://localhost:6274/oauth/callback/debug

8. http://localhost:3000/callback (Optional, for server-side redirection handling)

9. Credential Retrieval:

10. Copy the unique Application (client) ID from the Overview pane.

11. Navigate to Certificates & secrets → Generate a New client secret → Immediately copy the resulting secret value.

12. Environment Configuration: Establish a .env file in the project root directory: env MS365_MCP_CLIENT_ID=your-azure-ad-app-client-id-here MS365_MCP_CLIENT_SECRET=your-azure-ad-app-client-secret-here MS365_MCP_TENANT_ID=common

Once these environment variables are populated, the connector will default to utilizing your designated Azure application instead of the bundled default application.

3. External Token Provisioning (BYOT)

If this connector is integrated within a larger infrastructure responsible for managing Microsoft OAuth tokens externally, you possess the option to inject an access token directly:

bash MS365_MCP_OAUTH_TOKEN=your_oauth_token npx @softeria/ms-365-mcp-server

This technique:

• Completely circumvents the need for interactive authentication sequences.
• Utilizes the pre-existing OAuth credential for all communications with the Microsoft Graph API.
• Relieves this server of the responsibility for token lifecycle management, including refresh logic.

HTTP Mode Dependency: The HTTP transport layer mandates authentication. For testing authentication flows without active credentials, utilize stdio transport coupled with the device code flow.

Auth Tools Status: In HTTP mode, authentication operations (login/logout) are disabled by default, as OAuth handling is external. Activate them using the --enable-auth-tools CLI argument if local control is required.

Command-Line Interface Directives

The following parameters are recognized when executing the ms-365-mcp-server utility directly:

--login Initiate login using the device code protocol --logout Deactivate session and erase stored credentials --verify-login Check authentication status without commencing server operation --org-mode Activate organizational/work context from startup (grants access to Teams, SharePoint, etc.) --work-mode Synonym for --org-mode --force-work-scopes Backward compatibility flag for --org-mode (scheduled for deprecation)

Server Configuration Directives

When running as an active MCP gateway service, these directives apply:

-v Activate verbose diagnostic output --read-only Initialize the service in a mode preventing all modification operations --http [port] Employ Streamable HTTP transport over default stdio (optional port specification; default is 3000) Starts an embedded Express.js instance, exposing the MCP endpoint at /mcp --enable-auth-tools Permit login/logout operations even when running in HTTP mode (off by default in HTTP mode) --enabled-tools Restrict operational tools using a regular expression filter (e.g., "excel|contact" enables only Excel and Contact modules)

Corresponding Environment Variables:

• READ_ONLY=true|1: Alternative toggle for --read-only flag
• ENABLED_TOOLS: Tool filtering via regex pattern (alternative to --enabled-tools flag)
• MS365_MCP_ORG_MODE=true|1: Enable organizational mode (alternative to --org-mode flag)
• MS365_MCP_FORCE_WORK_SCOPES=true|1: Legacy setting for MS365_MCP_ORG_MODE
• LOG_LEVEL: Defines the verbosity level for logging (default: 'info')
• SILENT=true|1: Suppresses all console output
• MS365_MCP_CLIENT_ID: Custom Azure AD application client identifier (defaults to internal app)
• MS365_MCP_TENANT_ID: Custom tenant context identifier (defaults to 'common' for general access)
• MS365_MCP_OAUTH_TOKEN: Pre-loaded OAuth bearer token for Graph API requests (BYOT strategy)

Contribution Guidelines

We enthusiastically encourage community involvement! Prior to submitting any contribution via pull request, verify that your modifications adhere to our established quality benchmarks.

Execute the verification routine to confirm adherence to all code quality requirements:

bash npm run verify

Developer Workflow

Upon cloning the repository, code generation based on the Microsoft Graph OpenAPI specification may be necessary:

bash npm run generate

Assistance and Feedback

Should you encounter difficulties or require support:

• Report issues via the issue tracker
• Engage in community discussions
• Contact via electronic mail: eirikb@eirikb.no
• Join our community on Discord: https://discord.gg/WvGVNScrAZ or mention @eirikb

Licensing Information

MIT Licensed © 2025 Softeria

CLOUD COMPUTING DEFINITION (ISO Context): Cloud computing is defined as "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," as formalized by the International Organization for Standardization (ISO). This concept is widely recognized simply as "the cloud".

== Defining Attributes == In 2011, the United States National Institute of Standards and Technology (NIST) established five critical attributes characterizing cloud systems. The precise NIST definitions are enumerated below:

On-demand self-service: A consumer possesses the ability to automatically provision computing resources, such as processing duration and network storage capacity, as required, without any mandatory human mediation from the service provider. Broad network access: The capabilities provided must be accessible over a network utilizing standard interaction protocols, ensuring usability across a wide range of client devices (e.g., mobile devices, tablets, workstations, and laptops). Resource pooling: The vendor's computational assets are aggregated to serve multiple distinct consumers employing a multi-tenant architecture, where virtual and physical resources are dynamically allocated and reallocated according to fluctuating consumer demand. Rapid elasticity: Provisioning and de-provisioning of capabilities must occur with high speed, sometimes automatically, allowing the system to scale outward or inward rapidly in direct proportion to load fluctuations. From the consumer's perspective, available resources appear virtually limitless and can be commanded in any volume instantaneously. Measured service: Cloud systems incorporate intrinsic metering mechanisms to automatically monitor and optimize resource consumption, operating at an abstraction level suitable for the specific service type (e.g., data capacity, computational cycles, data transmission, and active user accounts). Resource utilization data must be trackable, controllable, and reportable, offering complete visibility to both the provider and the consumer of the consumed capacity. By the year 2023, the ISO had subsequently refined and extended this foundational list of characteristics.

== Historical Context ==

The conceptual roots of cloud computing trace back to the 1960s, marked by the popularization of time-sharing concepts facilitated through remote job entry (RJE) systems. During this period, the dominant operational model was the 'data center,' where users submitted computational tasks to dedicated operators who executed them on mainframe computers. This era was characterized by intense experimentation aimed at democratizing access to high-capacity computing power via time-sharing, optimizing underlying infrastructure, platform layers, and applications, thereby boosting end-user productivity. The specific 'cloud' metaphor, denoting virtualized services, originated around 1994 when it was employed by General Magic to describe the totality of 'locations' accessible by mobile software agents within their Telescript framework. This metaphorical usage is attributed to David Hoffman, an associate in communications at General Magic, drawing upon its established context within telecommunications and networking diagrams. The term 'cloud computing' gained broader recognition in 1996 following the development of a business strategy for future computation and the internet by Compaq Computer Corporation. The firm's objective was to achieve widespread comput