mcp-graphapi

rasta26/mcp-graphapi

3.2

If you are the rightful owner of mcp-graphapi and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Universal Microsoft Graph Intelligence server leverages the Model Context Protocol (MCP) to transform the Microsoft 365 ecosystem into intelligent, conversational interfaces.

Tools
4
Resources
0
Prompts
0

Universal Microsoft Graph Intelligence 🚀

Complete M365 ecosystem through conversational AI

TypeScript Azure MCP

🌟 The Vision

Transform your entire Microsoft 365 ecosystem into intelligent, conversational interfaces. This universal MCP server provides seamless access to Azure AD, Security Center, and Intune through natural language interactions.

✨ Universal Capabilities

👥 Azure Active Directory

  • User management and search
  • Group administration
  • Role and permission analysis
  • Sign-in activity monitoring

🛡️ Security Center

  • Real-time threat detection
  • Security alerts and incidents
  • Risk assessment and scoring
  • Identity protection insights

📱 Intune Device Management

  • Comprehensive device inventory
  • Compliance monitoring
  • Application management
  • Mobile device insights

🛠️ Available Tools

Azure AD Tools

ToolDescriptionParameters
get_usersRetrieve all Azure AD usersNone
search_usersSearch users by name/emailquery: string
get_groupsList all Azure AD groupsNone
get_user_rolesGet user role membershipsuserId: string

Security Tools

ToolDescriptionParameters
get_security_alertsRetrieve security alertsNone
get_risk_detectionsGet identity risk detectionsNone
get_security_scoreOrganization security scoreNone

Intune Tools

ToolDescriptionParameters
get_intune_devicesRetrieve managed devicesNone
search_intune_devicesSearch devices by name/emailquery: string
get_compliance_reportDevice compliance summaryNone
export_device_reportExport device/compliance reportsreportType?: string
get_device_ringsList deployment ringsNone
lookup_device_ringFind device ring assignmentsdeviceId: string

🚀 Quick Start

Prerequisites

  • Node.js 18+
  • Azure AD application with Microsoft Graph permissions
  • Access to Microsoft 365 services

Installation

git clone <repository-url>
cd mcp-graphapi
npm install
npm run build

Configuration

cp .env.example .env
# Configure your Azure AD credentials and logging level
# LOG_LEVEL options: ERROR, WARN, INFO, DEBUG

Testing & Validation

# Test Azure Graph API connection
npm run test-connection

# Test MCP server functionality  
node test-server.js

# Validate MCP configuration
node test-mcp-config.js

MCP Integration (VSCode)

The project includes MCP configuration for VSCode:

  • Local: .vscode/mcp.json (project-specific)
  • Global: See MCP-SETUP.md for system-wide setup

Run Server

npm start

🔧 Azure AD Setup

Required API Permissions

Microsoft Graph → Application permissions:
├── User.Read.All (Azure AD users)
├── Group.Read.All (Azure AD groups)  
├── Directory.Read.All (Directory info)
├── DeviceManagementManagedDevices.Read.All (Intune)
├── DeviceManagementApps.Read.All (Intune apps)
├── SecurityEvents.Read.All (Security alerts)
├── IdentityRiskEvent.Read.All (Risk detections)
└── SecurityActions.Read.All (Security score)

Setup Steps

  1. Register Application in Azure Portal
  2. Add API Permissions (see list above)
  3. Grant Admin Consent for all permissions
  4. Create Client Secret
  5. Update .env with credentials

🏗️ Architecture

graph TB
    A[AI Assistant] --> B[MCP Server]
    B --> C[Azure Auth]
    B --> D[Azure AD Service]
    B --> E[Security Service]
    B --> F[Intune Service]
    
    D --> G[Microsoft Graph API]
    E --> G
    F --> G
    
    G --> H[Azure Active Directory]
    G --> I[Security Center]
    G --> J[Intune]

📝 Development

Scripts

  • npm run build - Compile TypeScript
  • npm run dev - Development with hot reload
  • npm start - Run compiled server
  • npm run clean - Clean build output
  • npm run test-connection - Test Azure connectivity

Logging

Set log level via environment variable:

LOG_LEVEL=DEBUG npm start  # DEBUG, INFO, WARN, ERROR

Testing

node test-server.js

🔒 Security Features

  • Zero-Trust Authentication - Azure AD client credentials
  • Automatic Token Refresh - Seamless session management
  • Minimal Permissions - Least privilege access
  • Secure Configuration - Environment-based secrets

🤝 Contributing

  1. Fork the repository
  2. Create feature branch
  3. Implement changes
  4. Add tests
  5. Submit pull request

📄 License

MIT License - see LICENSE file for details

🆘 Troubleshooting

Common Issues

Authentication Error:

invalid_client_credential: Client credential must not be empty
  • Verify .env file exists with valid credentials
  • Check Azure AD application permissions
  • Ensure admin consent granted

Permission Denied:

Insufficient privileges to complete the operation
  • Verify all required Graph API permissions added
  • Confirm admin consent granted for permissions
  • Check service principal has correct roles

Module Resolution:

Cannot find module
  • Run npm run build to compile TypeScript
  • Ensure all dependencies installed with npm install

📞 Support

For issues and questions:

  • Create GitHub issue
  • Review troubleshooting section
  • Check Azure AD configuration