g-mercuri/mcp-entra-graph

MCP Entra Graph

A Model Context Protocol (MCP) server built with Python and FastMCP that provides seamless integration with Microsoft Entra ID (formerly Azure AD) for user and group management through Microsoft Graph API.

This server uses streamable HTTP transport, which means it runs as an HTTP server that supports streaming responses, making it compatible with web-based MCP clients like GitHub Copilot, enabling efficient, real-time communication.

Features

This MCP server provides the following tools for managing Microsoft Entra ID:

User Management

• find_user_by_name - Search for users by display name, first name, or last name
  • Case-insensitive partial matching
  • Returns user ID, display name, email, and job title

Group Management

• search_groups - Find groups by display name
• get_group_info - Get detailed information about a specific group
• list_group_members - List all members of a group
• add_user_to_group - Add a user to a group
• remove_user_from_group - Remove a user from a group

What is MCP?

The Model Context Protocol (MCP) is an open standard protocol that enables seamless integration between AI applications and data sources. Think of it as a universal connector that allows AI assistants to securely access and interact with your tools and data.

How This Server Works

This server is built with FastMCP, a Python framework that simplifies building MCP servers. It:

1. Exposes Tools: Makes Entra ID management functions available to AI assistants as callable tools
2. Uses Streamable HTTP: Runs as an HTTP server on localhost:8000, supporting streaming responses for real-time interaction
3. Authenticates Securely: Uses Azure AD application credentials to access Microsoft Graph API
4. Returns Structured Data: Provides JSON responses that AI assistants can understand and use

When you ask an AI assistant like GitHub Copilot to "find users named John", the assistant:

• Detects it needs the find_user_by_name tool
• Calls this MCP server via HTTP
• The server authenticates with Microsoft Graph
• Returns the results to the AI, which presents them to you

Prerequisites

• Python 3.10 or higher (required for FastMCP and async features)
• pip (Python package manager, usually included with Python)
• Microsoft Entra ID tenant with admin permissions
• Azure Portal access for app registration
• Node.js and npm (optional, only needed for MCP Inspector debugging tool)

Installation

1. Clone the Repository

git clone https://github.com/g-mercuri/mcp-entra-graph.git
cd mcp-entra-graph

2. Create a Virtual Environment

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1

Linux/macOS:

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

4. Register an Azure AD Application

1. Navigate to Azure Portal → Azure Active Directory → App registrations
2. Click New registration
   • Name: Entra ID MCP Server (or your preferred name)
   • Supported account types: Single tenant
   • Click Register
3. Note the Application (client) ID and Directory (tenant) ID
4. Go to Certificates & secrets → New client secret
   • Add a description and expiration period
   • Copy the Value (client secret) - you won't be able to see it again
5. Go to API permissions → Add a permission → Microsoft Graph → Application permissions
   • Add the following permissions:
     • Group.ReadWrite.All - Read and write all groups
     • User.Read.All - Read all users' full profiles
     • Directory.ReadWrite.All - Read and write directory data
6. Click Grant admin consent for your tenant

5. Configure Environment Variables

Create a .env file in the project root:

TENANT_ID=your-tenant-id-here
CLIENT_ID=your-client-id-here
CLIENT_SECRET=your-client-secret-here

Note: You can use .env.example as a template if available.

Usage

Starting the Server

python src/server.py

The server will start on http://127.0.0.1:8000 by default using streamable HTTP transport.

You should see output similar to:

INFO:__main__:Starting Entra ID MCP Server with Streamable HTTP transport...

Using with GitHub Copilot (VS Code)

1. Start the MCP server (see above)

2. Configure VS Code by creating/editing mcp.json:

   Method 1: Automatic

   • Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
   • Select "GitHub Copilot: Add MCP Server"
   • Follow the prompts

   Method 2: Manual

   • Create .vscode/mcp.json in your workspace:

   {
     "servers": {
       "entra-id": {
         "url": "http://127.0.0.1:8000",
         "type": "http"
       }
     }
   }
   

3. Reload VS Code

   • Press Ctrl+Shift+P → "Developer: Reload Window"

4. Use in Copilot Chat

   • Open GitHub Copilot Chat
   • The Entra ID tools will be automatically available
   • Example: "Find users named John" or "Add user to the Developers group"

Using with MCP Inspector (Debugging)

For testing and debugging MCP requests:

npx @modelcontextprotocol/inspector http://127.0.0.1:8000

This opens an interactive interface to explore and test all available tools.

Example Interactions

Once configured with an MCP client, you can interact naturally:

• "Find all users with the last name Smith"
• "List all members of the Engineering group"
• "Add John Doe to the Developers group"
• "Search for groups containing 'marketing'"
• "Show me information about the Sales group"

The AI assistant will use the appropriate tools to fulfill these requests.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - See file for details