JBAssist - Microsoft Graph MCP Server

Created By

JBAgent9 months ago

A Windows-compatible MCP server for querying Microsoft Graph API

Content

JBAssist - Microsoft Graph MCP Server

A Windows-compatible implementation of the Model Context Protocol (MCP) server that connects Claude Desktop to Microsoft Graph API.

Overview

This project provides a simple MCP server that allows Claude to interact with Microsoft 365 services through Microsoft Graph API. The server offers a variety of tools to access both standard and beta Graph API features.

Standard API Tools

get-profile: Get the current user's profile information
get-emails: Retrieve recent emails from the user's inbox
get-calendar-events: Get upcoming calendar events for the specified number of days
search-users: Search for users in the organization

Beta API Tools (Extended User Features)

get-enhanced-profile: Get detailed user profile info including skills, interests, schools, and more
get-direct-reports: Get a user's direct reports with detailed information
get-manager: Get a user's manager information
get-presence: Get a user's presence information (availability status)
get-teamwork: Get a user's Microsoft Teams and teamwork activity
advanced-user-search: Search for users with advanced filtering by skills, department, job title

Prerequisites

Node.js version 18 or higher
Claude Desktop with MCP support
Windows 10 or 11
Microsoft 365 account with appropriate permissions
Azure AD App Registration with appropriate permissions

Setup

1. Create an Azure AD App Registration

Go to the Azure Portal and navigate to Azure Active Directory
Select "App registrations" and click "New registration"
Enter a name for your application (e.g., "JBAssist")
Select "Accounts in this organizational directory only" for Supported account types
Click "Register"
Note the "Application (client) ID" and "Directory (tenant) ID" values
Under "Certificates & secrets", create a new client secret and note its value

2. Configure API Permissions

In your App Registration, go to "API permissions"
Click "Add a permission" and select "Microsoft Graph"
Choose "Application permissions" (for daemon/service access) or "Delegated permissions" (for user access)
Add the following permissions:
- User.Read
- Mail.Read
- Calendars.Read
- User.Read.All (for user search)
- Presence.Read.All (for presence information)
- TeamMember.Read.All (for Teams information)
Click "Add permissions"
Click "Grant admin consent for [your organization]"

3. Clone and Configure the Repository

Clone this repository:

git clone https://github.com/JBAgent/JBAssist.git
cd JBAssist

Create a .env file based on the .env.example template:
```
cp .env.example .env
```

Edit the .env file with your Azure AD app details:

TENANT_ID=your-tenant-id
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
SCOPES=User.Read,Mail.Read,Calendars.Read,User.Read.All,Presence.Read.All,TeamMember.Read.All

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

Running the Microsoft Graph Server with Claude Desktop

First, start Claude Desktop
Run the server using one of the following methods:
- PowerShell:
```
.\run-graph-server.ps1
```
- Command Prompt:
```
run-graph-server.bat
```
- Or directly with Node.js:
```
npm start
```
In Claude Desktop, click the puzzle piece icon (🧩) in the top-right corner to open the MCP server selector
Select "Add MCP Server" and enter msgraph when prompted for the server name
You should see confirmation that the Microsoft Graph server has connected successfully

Using the Microsoft Graph Tools

Once connected, you can ask Claude to use the MS Graph tools with natural language, for example:

Standard API Examples

"Can you show me my profile information?"
"What are my recent emails?"
"Show me my calendar events for the next week."
"Can you search for users with the name John?"

Beta API Examples

"Get my enhanced profile with skills and interests."
"Who are my direct reports?"
"Who is my manager?"
"What's my current presence status?"
"Show me my Teams information."
"Search for users in the Marketing department who have SQL skills."

Beta API Features

The Microsoft Graph beta API provides access to features that are still in development. These features are subject to change and may not be stable. The beta API provides access to:

Enhanced User Profiles

The beta API offers expanded user profile information, including:

Skills and expertise
Interests
Past projects
Education history
Responsibilities
About me information
Birthday
Preferred languages
Alternative email addresses

Organizational Relationships

Direct reports hierarchy
Manager information
Team memberships
Team presence and status

Presence Information

User availability status
Activity information
Status messages
Teams presence information

Advanced Search

Search by skills
Search by department
Search by job title
Combined search with multiple filters

Troubleshooting

If you encounter issues:

Authentication Errors: Double-check your Azure AD app credentials in the .env file
Permission Errors: Ensure your Azure AD app has the appropriate permissions granted
Connection Errors: Make sure you've clicked the "Allow" button when Claude Desktop prompts for MCP permission
Log Files: Check the graph-server.log file for detailed error information
Path Issues: Ensure Node.js and npm are in your system's PATH variable
Permission Errors in Windows: Try running Command Prompt or PowerShell as Administrator
Beta API Errors: Remember that beta API endpoints may change or behave differently than documented