microsoft-graph-mcp

Microsoft 365 integration for AI assistants - Connect Cursor, Claude Desktop, and other MCP-compatible tools directly to Microsoft Graph. Access Outlook, OneDrive, Calendar, Teams, and automate workflows with AI.

✅ What we provide (this project)

Deliverable | Description --- | --- AI-ready MCP server | Exposes Microsoft Graph capabilities as MCP tools for AI assistants REST gateway for Microsoft Graph | Local HTTP API with OpenAPI/Swagger at /docs Prebuilt Microsoft 365 endpoints | Users, Mail (send/reply/forward), Calendar (CRUD events), Files/OneDrive (list/upload/delete), Teams (teams/channels), Groups (members), Contacts, Tasks, Subscriptions (webhooks), Applications, Directory, Organization, People Authentication via Azure AD | App Registration flow using AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID Production-ready scaffolding | Port/config management, error handling, health checks, API info, logging Tested TypeScript implementation | Type-safe code with Jest tests covering all endpoints Developer UX | Copy-pasteable curl examples, Swagger try-it-out, easy local run with npx Security posture | Uses Application permissions; no data persisted by the server

📊 Microsoft Graph Overview

Microsoft Graph connects users, their activities, and content across Microsoft 365 services - Teams, Calendar, Files, Mail, People, Tasks, and more. This MCP server provides AI assistants with direct access to this unified data layer.

🚀 Quick Start

Run with npx (Recommended)

AZURE_CLIENT_ID=your-client-id \
AZURE_CLIENT_SECRET=your-client-secret \
AZURE_TENANT_ID=your-tenant-id \
npx microsoft-graph-mcp

That's it! The server runs on:

Service | URL | Notes --- | --- | --- REST API | http://localhost:8887 | Base URL for all endpoints API Docs (Swagger) | http://localhost:8887/docs | Interactive documentation MCP Server | http://localhost:8888 | Model Context Protocol server

Run with .env file

Create a .env file:

AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=your-tenant-id

Then run:

npx microsoft-graph-mcp

📋 Azure Configuration

Step 1: Create Azure App Registration

1. Go to Azure Portal
2. Navigate to Azure Active Directory > App registrations
3. Click New registration
4. Fill in:
   • Name: Microsoft Graph MCP Server
   • Supported account types: Accounts in this organizational directory only (or Multi-tenant)
   • Click Register

Step 2: Get Credentials

1. Application (client) ID → Copy this as AZURE_CLIENT_ID
2. Directory (tenant) ID → Copy this as AZURE_TENANT_ID
3. Go to Certificates & secrets → New client secret
   • Copy the secret value as AZURE_CLIENT_SECRET (only shown once!)

Step 3: Add Application Permissions

1. Go to API permissions → Add a permission → Microsoft Graph → Application permissions

2. Add these permissions:

   Permission | Type | Description --- | --- | --- User.Read.All | Application | Read all users Mail.Read | Application | Read mail in all mailboxes Mail.Send | Application | Send mail as any user Calendars.Read | Application | Read calendars in all mailboxes Files.Read.All | Application | Read all files Group.Read.All | Application | Read all groups Contacts.Read | Application | Read contacts Tasks.ReadWrite.All | Application | Read and write tasks Organization.Read.All | Application | Read organization information People.Read.All | Application | Read people profiles Application.Read.All | Application | Read applications Subscription.Read.All | Application | Manage subscriptions

3. ⚠️ CRITICAL: Click Grant admin consent for [your organization]

💻 Use in Cursor / Claude Desktop

Cursor Configuration

1. Open Cursor Settings → Features → Model Context Protocol
2. Click "Edit Config"
3. Add:

{
  "mcpServers": {
    "microsoft-graph-mcp": {
      "command": "npx",
      "args": ["-y", "microsoft-graph-mcp"],
      "env": {
        "AZURE_CLIENT_ID": "your-client-id",
        "AZURE_CLIENT_SECRET": "your-client-secret",
        "AZURE_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

Claude Desktop Configuration

1. Open config file:

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the same configuration as above

3. Restart Claude Desktop

📡 Using the REST API

Once the server is running, you have full access to Microsoft Graph via REST endpoints.

🔍 Interactive API Documentation

Swagger UI (Recommended - Visual Interface):

http://localhost:8887/docs

• Browse all endpoints
• Try requests directly in the browser
• See request/response schemas

OpenAPI JSON:

http://localhost:8887/openapi.json

• Import into Postman, Insomnia, or any OpenAPI-compatible tool

📝 Common API Examples

Get Users

curl "http://localhost:8887/graph/users?$top=10"

Get Email Messages

curl "http://localhost:8887/graph/[email protected]&$top=10"

Send an Email

curl -X POST http://localhost:8887/graph/mail \
  -H "Content-Type: application/json" \
  -d '{
    "toRecipients": [{"emailAddress": {"address": "[email protected]"}}],
    "subject": "Hello from microsoft-graph-mcp!",
    "body": {"contentType": "text", "content": "This is a test message"}
  }'

Get Calendar Events

curl "http://localhost:8887/graph/[email protected]&$top=10"

Create Calendar Event

curl -X POST http://localhost:8887/graph/calendar/events \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Team Meeting",
    "start": {"dateTime": "2024-01-15T10:00:00", "timeZone": "UTC"},
    "end": {"dateTime": "2024-01-15T11:00:00", "timeZone": "UTC"},
    "userId": "[email protected]"
  }'

Get OneDrive Files

curl "http://localhost:8887/graph/[email protected]&$top=20"

Get Teams

curl http://localhost:8887/graph/teams

📚 All Available Endpoints

Users (6 endpoints)

Method | Path | Description --- | --- | --- GET | /graph/users | Get list of users (supports filtering, pagination) GET | /graph/users/:userId | Get specific user by ID POST | /graph/users | Create new user PATCH | /graph/users/:userId | Update user DELETE | /graph/users/:userId | Delete user GET | /graph/users/:userId/photo | Get user photo

Mail (7 endpoints)

Method | Path | Description --- | --- | --- GET | /graph/[email protected] | Get email messages (supports filtering) GET | /graph/mail/:[email protected] | Get specific message POST | /graph/mail | Send email message POST | /graph/mail/:messageId/[email protected] | Reply to message POST | /graph/mail/:messageId/[email protected] | Forward message DELETE | /graph/mail/:[email protected] | Delete message GET | /graph/mail/[email protected] | Get mail folders

Calendar (5 endpoints)

Method | Path | Description --- | --- | --- GET | /graph/[email protected] | Get calendar events (supports filtering) GET | /graph/[email protected] | Get user calendars POST | /graph/calendar/events | Create calendar event (include userId in body) PATCH | /graph/calendar/events/:[email protected] | Update calendar event DELETE | /graph/calendar/events/:[email protected] | Delete calendar event

Files/OneDrive (4 endpoints)

Method | Path | Description --- | --- | --- GET | /graph/[email protected] | Get files and folders from OneDrive GET | /graph/[email protected] | Get drives (OneDrive and SharePoint) POST | /graph/files/upload | Upload file to OneDrive (include userId in body) DELETE | /graph/files/:[email protected] | Delete file or folder

Groups (3 endpoints)

Method | Path | Description --- | --- | --- GET | /graph/groups | Get list of groups POST | /graph/groups | Create new group GET | /graph/groups/:groupId/members | Get group members

Teams (2 endpoints)

Method | Path | Description --- | --- | --- GET | /graph/teams | Get list of teams GET | /graph/teams/:teamId/channels | Get team channels

Contacts (2 endpoints)

Method | Path | Description --- | --- | --- GET | /graph/[email protected] | Get contacts POST | /graph/contacts | Create contact (include userId in body)

Tasks (2 endpoints)

Method | Path | Description --- | --- | --- GET | /graph/[email protected] | Get tasks/to-do items POST | /graph/tasks | Create task (include userId in body)

Additional Services

Method | Path | Description --- | --- | --- GET | /graph/applications | Get applications GET | /graph/directory | Get directory objects GET | /graph/organization | Get organization information GET | /graph/[email protected] | Get people (colleagues and contacts) GET | /graph/subscriptions | Get webhook subscriptions POST | /graph/subscriptions | Create webhook subscription

System

Method | Path | Description --- | --- | --- GET | /health | Health check GET | /api-info | API information GET | /openapi.json | OpenAPI specification GET | /docs | Swagger UI documentation

All endpoints are automatically exposed as MCP tools for AI agents to use.

⚙️ Advanced Configuration

Environment Variables

Variable | Required | Default | Description --- | --- | --- | --- AZURE_CLIENT_ID | Yes | - | Azure AD application (client) ID AZURE_CLIENT_SECRET | Yes | - | Azure AD client secret (value) AZURE_TENANT_ID | Yes | - | Azure AD directory (tenant) ID AZURE_SCOPE | No | https://graph.microsoft.com/.default | Microsoft Graph scope EASY_MCP_SERVER_PORT | No | 8887 | REST API port EASY_MCP_SERVER_MCP_PORT | No | 8888 | MCP server port EASY_MCP_SERVER_LOG_LEVEL | No | info | Logging level

🎯 Use Cases

In Cursor / Claude Desktop

• "Get my latest emails from Outlook"
• "Create a calendar event for tomorrow at 2pm"
• "Show me files in my OneDrive"
• "List all Microsoft Teams in the organization"
• "Send an email to [email protected] about the project update"
• "What contacts do I have?"

Via REST API

• Build custom Microsoft 365 integrations
• Automate workflows
• Create Microsoft Graph applications
• Integrate with other services

Via Swagger UI

• Explore endpoints visually
• Test API calls
• Understand request/response formats
• Share API documentation

🔧 Troubleshooting

Server won't start

• ✅ Check that port 8887/8888 is not in use
• ✅ Verify your Azure credentials are correct in .env
• ✅ Ensure Node.js >= 22.0.0 is installed

Authentication errors

• ✅ Verify AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID are correct
• ✅ Check that admin consent has been granted for all required permissions
• ✅ Verify the client secret hasn't expired (create a new one if needed)
• ✅ Ensure permissions are configured as "Application permissions" (not Delegated)

"Insufficient privileges" errors

• ✅ Verify all required permissions are added in Azure Portal
• ✅ Ensure admin consent has been granted
• ✅ Check that permissions are Application permissions (not Delegated)

MCP not working in Cursor/Claude

• ✅ Restart Cursor/Claude after adding MCP config
• ✅ Check server is running (curl http://localhost:8887/health)
• ✅ Verify environment variables are set correctly
• ✅ Check Cursor/Claude logs for MCP errors

API calls returning errors

• ✅ Test authentication: curl http://localhost:8887/graph/users/me
• ✅ Check Swagger UI: http://localhost:8887/docs
• ✅ Verify Azure app has required permissions
• ✅ Review server logs for detailed error messages

📖 Learn More

• Microsoft Graph API: https://learn.microsoft.com/en-us/graph/overview
• Model Context Protocol: https://modelcontextprotocol.io/

📦 Package Info

• npm: microsoft-graph-mcp
• Repository: GitHub
• License: MIT

🆘 Need Help?

1. Check Swagger UI: http://localhost:8887/docs
2. Test authentication: curl http://localhost:8887/graph/users/me
3. Check server health: curl http://localhost:8887/health
4. Review the Azure Configuration section above
5. For customization and enterprise support, contact: [email protected]

🛠️ Development

This MCP server is built using the easy-mcp-server framework.

For development documentation, including:

• How to create custom endpoints
• Project structure and architecture
• Testing and debugging
• Contributing guidelines

👉 See the easy-mcp-server documentation for development details.

📦 Package Info

• npm: microsoft-graph-mcp
• Repository: GitHub
• License: MIT

Powered by easy-mcp-server framework