hieutran/entraid-mcp-server

This project provides a modular, resource-oriented FastMCP server for interacting with Microsoft Graph API. It is designed for extensibility, maintainability, and security, supporting advanced queries for users, sign-in logs, MFA status, and privileged users.
Features
- **Modular Resource Structure:**
- Each resource (users, sign-in logs, MFA, etc.) is implemented in its own module under src/msgraph_mcp_server/resources/.
- Easy to extend with new resources (e.g., groups, devices).
- **Centralized Graph Client:**
- Handles authentication and client initialization.
- Shared by all resource modules.
- **Comprehensive User Operations:**
- Search users by name/email.
- Get user by ID.
- List all privileged users (directory role members).
- **Full Group Lifecycle & Membership Management:**
- Create, read, update, and delete groups.
- Add/remove group members and owners.
- Search and list groups and group members.
- **Application & Service Principal Management:**
- List, create, update, and delete applications (app registrations).
- List, create, update, and delete service principals.
- View app role assignments and delegated permissions for both applications and service principals.
- **Sign-in Log Operations:**
- Query sign-in logs for a user for the last X days.
- **MFA Operations:**
- Get MFA status for a user.
- Get MFA status for all members of a group.
- **Password Management:**
- Reset user passwords directly with custom or auto-generated secure passwords.
- Option to require password change on next sign-in.
- **Permissions Helper:**
- Suggest appropriate Microsoft Graph permissions for common tasks.
- Search and explore available Graph permissions.
- Helps implement the principle of least privilege by recommending only necessary permissions.
- **Error Handling & Logging:**
- Consistent error handling and progress reporting via FastMCP context.
- Detailed logging for troubleshooting.
- **Security:**
- .env and secret files are excluded from version control.
- Uses Microsoft best practices for authentication.
Project Structure
Usage
1. Setup
- Clone the repo.
- Create a config/.env file with your Azure AD credentials:
- (Optional) Set up certificate-based auth if needed.
2. Testing & Development
You can test and develop your MCP server directly using the FastMCP CLI:
This launches an interactive development environment with the MCP Inspector. For more information and advanced usage, see the FastMCP documentation.
3. Available Tools
User Tools
- search_users(query, ctx, limit=10) — Search users by name/email
- get_user_by_id(user_id, ctx) — Get user details by ID
- get_privileged_users(ctx) — List all users in privileged directory roles
- get_user_roles(user_id, ctx) — Get all directory roles assigned to a user
- get_user_groups(user_id, ctx) — Get all groups (including transitive memberships) for a user
Group Tools
- get_all_groups(ctx, limit=100) — Get all groups (with paging)
- get_group_by_id(group_id, ctx) — Get a specific group by its ID
- search_groups_by_name(name, ctx, limit=50) — Search for groups by display name
- get_group_members(group_id, ctx, limit=100) — Get members of a group by group ID
- create_group(ctx, group_data) — Create a new group (see below for group_data fields)
- update_group(group_id, ctx, group_data) — Update an existing group (fields: displayName, mailNickname, description, visibility)
- delete_group(group_id, ctx) — Delete a group by its ID
- add_group_member(group_id, member_id, ctx) — Add a member (user, group, device, etc.) to a group
- remove_group_member(group_id, member_id, ctx) — Remove a member from a group
- add_group_owner(group_id, owner_id, ctx) — Add an owner to a group
- remove_group_owner(group_id, owner_id, ctx) — Remove an owner from a group