EntraID MCP Server (Microsoft Graph FastMCP)

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

src/msgraph_mcp_server/
├── auth/           # Authentication logic (GraphAuthManager)
├── resources/      # Resource modules (users, signin_logs, mfa, ...)
│   ├── users.py            # User operations (search, get by ID, etc.)
│   ├── signin_logs.py      # Sign-in log operations
│   ├── mfa.py              # MFA status operations
│   ├── permissions_helper.py # Graph permissions utilities and suggestions
│   ├── applications.py       # Application (app registration) operations
│   ├── service_principals.py # Service principal operations
│   └── ...                 # Other resource modules
├── utils/          # Core GraphClient and other ultilities tool, such as password generator..
├── server.py       # FastMCP server entry point (registers tools/resources)
├── __init__.py     # Package marker

Usage

1. Setup

Clone the repo.

Create a config/.env file with your Azure AD credentials:

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

(Optional) Set up certificate-based auth if needed.

2. Testing & Development

You can test and develop your MCP server directly using the FastMCP CLI:

fastmcp dev '/path/to/src/msgraph_mcp_server/server.py'

This launches an interactive development environment with the MCP Inspector. For more information and advanced usage, see the FastMCP documentation.

3. Available 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

Group Creation/Update Example:

group_data for create_group and update_group should be a dictionary with keys such as:
- displayName (required for create)
- mailNickname (required for create)
- description (optional)
- groupTypes (optional, e.g., ["Unified"])
- mailEnabled (optional)
- securityEnabled (optional)
- visibility (optional, "Private" or "Public")
- owners (optional, list of user IDs)
- members (optional, list of IDs)
- membershipRule (required for dynamic groups)
- membershipRuleProcessingState (optional, "On" or "Paused")

See the groups.py docstrings for more details on supported fields and behaviors.

get_user_sign_ins(user_id, ctx, days=7) — Get sign-in logs for a user

MFA Tools

get_user_mfa_status(user_id, ctx) — Get MFA status for a user
get_group_mfa_status(group_id, ctx) — Get MFA status for all group members

Device Tools

get_all_managed_devices(filter_os=None) — Get all managed devices (optionally filter by OS)
get_managed_devices_by_user(user_id) — Get all managed devices for a specific user

Conditional Access Policy Tools

get_conditional_access_policies(ctx) — Get all conditional access policies
get_conditional_access_policy_by_id(policy_id, ctx) — Get a single conditional access policy by its ID

Audit Log Tools

get_user_audit_logs(user_id, days=30) — Get all relevant directory audit logs for a user by user_id within the last N days

Password Management Tools

reset_user_password_direct(user_id, password=None, require_change_on_next_sign_in=True, generate_password=False, password_length=12) — Reset a user's password with a specific password value or generate a secure random password

Permissions Helper Tools

suggest_permissions_for_task(task_category, task_name) — Suggest Microsoft Graph permissions for a specific task based on common mappings
list_permission_categories_and_tasks() — List all available categories and tasks for permission suggestions
get_all_graph_permissions() — Get all Microsoft Graph permissions directly from the Microsoft Graph API
search_permissions(search_term, permission_type=None) — Search for Microsoft Graph permissions by keyword

Application Tools

list_applications(ctx, limit=100) — List all applications (app registrations) in the tenant, with paging
get_application_by_id(app_id, ctx) — Get a specific application by its object ID (includes app role assignments and delegated permissions)
create_application(ctx, app_data) — Create a new application (see below for app_data fields)
update_application(app_id, ctx, app_data) — Update an existing application (fields: displayName, signInAudience, tags, identifierUris, web, api, requiredResourceAccess)
delete_application(app_id, ctx) — Delete an application by its object ID

Application Creation/Update Example:

app_data for create_application and update_application should be a dictionary with keys such as:
- displayName (required for create)
- signInAudience (optional)
- tags (optional)
- identifierUris (optional)
- web (optional)
- api (optional)
- requiredResourceAccess (optional)

Service Principal Tools

list_service_principals(ctx, limit=100) — List all service principals in the tenant, with paging
get_service_principal_by_id(sp_id, ctx) — Get a specific service principal by its object ID (includes app role assignments and delegated permissions)
create_service_principal(ctx, sp_data) — Create a new service principal (see below for sp_data fields)
update_service_principal(sp_id, ctx, sp_data) — Update an existing service principal (fields: displayName, accountEnabled, tags, appRoleAssignmentRequired)
delete_service_principal(sp_id, ctx) — Delete a service principal by its object ID

Service Principal Creation/Update Example:

sp_data for create_service_principal and update_service_principal should be a dictionary with keys such as:
- appId (required for create)
- accountEnabled (optional)
- tags (optional)
- appRoleAssignmentRequired (optional)
- displayName (optional)

Example Resource

greeting://{name} — Returns a personalized greeting

Extending the Server

Add new resource modules under resources/ (e.g., groups.py, devices.py).
Register new tools in server.py using the FastMCP @mcp.tool() decorator.
Use the shared GraphClient for all API calls.

Security & Best Practices

Never commit secrets: .env and other sensitive files are gitignored.
Use least privilege: Grant only the necessary Microsoft Graph permissions to your Azure AD app.
Audit & monitor: Use the logging output for troubleshooting and monitoring.

Required Graph API Permissions

API / Permission	Type	Description
AuditLog.Read.All	Application	Read all audit log data
AuthenticationContext.Read.All	Application	Read all authentication context information
DeviceManagementManagedDevices.Read.All	Application	Read Microsoft Intune devices
Directory.Read.All	Application	Read directory data
Group.Read.All	Application	Read all groups
GroupMember.Read.All	Application	Read all group memberships
Group.ReadWrite.All	Application	Create, update, delete groups; manage group members and owners
Policy.Read.All	Application	Read your organization's policies
RoleManagement.Read.Directory	Application	Read all directory RBAC settings
User.Read.All	Application	Read all users' full profiles
User-PasswordProfile.ReadWrite.All	Application	Least privileged permission to update the passwordProfile property
UserAuthenticationMethod.Read.All	Application	Read all users' authentication methods
Application.ReadWrite.All	Application	Create, update, and delete applications (app registrations) and service principals

Note: Group.ReadWrite.All is required for group creation, update, deletion, and for adding/removing group members or owners. Group.Read.All and GroupMember.Read.All are sufficient for read-only group and membership queries.

Advanced: Using with Claude or Cursor

Using with Claude (Anthropic)

To install and run this server as a Claude MCP tool, use:

fastmcp install '/path/to/src/msgraph_mcp_server/server.py' \
  --with msgraph-sdk --with azure-identity --with azure-core --with msgraph-core \
  -f /path/to/.env

Replace /path/to/ with your actual project path.
The -f flag points to your .env file (never commit secrets!).

Using with Cursor

Add the following to your .cursor/mcp.json (do not include actual secrets in version control):

{
  "EntraID MCP Server": {
    "command": "uv",
    "args": [
      "run",
      "--with", "azure-core",
      "--with", "azure-identity",
      "--with", "fastmcp",
      "--with", "msgraph-core",
      "--with", "msgraph-sdk",
      "fastmcp",
      "run",
      "/path/to/src/msgraph_mcp_server/server.py"
    ],
    "env": {
      "TENANT_ID": "<your-tenant-id>",
      "CLIENT_ID": "<your-client-id>",
      "CLIENT_SECRET": "<your-client-secret>"
    }
  }
}

Replace /path/to/ and the environment variables with your actual values.
Never commit real secrets to your repository!

License

MIT

EntraID MCP Server (Microsoft Graph FastMCP)

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

src/msgraph_mcp_server/
├── auth/           # Authentication logic (GraphAuthManager)
├── resources/      # Resource modules (users, signin_logs, mfa, ...)
│   ├── users.py            # User operations (search, get by ID, etc.)
│   ├── signin_logs.py      # Sign-in log operations
│   ├── mfa.py              # MFA status operations
│   ├── permissions_helper.py # Graph permissions utilities and suggestions
│   ├── applications.py       # Application (app registration) operations
│   ├── service_principals.py # Service principal operations
│   └── ...                 # Other resource modules
├── utils/          # Core GraphClient and other ultilities tool, such as password generator..
├── server.py       # FastMCP server entry point (registers tools/resources)
├── __init__.py     # Package marker

Usage

1. Setup

Clone the repo.

Create a config/.env file with your Azure AD credentials:

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

(Optional) Set up certificate-based auth if needed.

2. Testing & Development

You can test and develop your MCP server directly using the FastMCP CLI:

fastmcp dev '/path/to/src/msgraph_mcp_server/server.py'

This launches an interactive development environment with the MCP Inspector. For more information and advanced usage, see the FastMCP documentation.

3. Available 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

Group Creation/Update Example:

group_data for create_group and update_group should be a dictionary with keys such as:
- displayName (required for create)
- mailNickname (required for create)
- description (optional)
- groupTypes (optional, e.g., ["Unified"])
- mailEnabled (optional)
- securityEnabled (optional)
- visibility (optional, "Private" or "Public")
- owners (optional, list of user IDs)
- members (optional, list of IDs)
- membershipRule (required for dynamic groups)
- membershipRuleProcessingState (optional, "On" or "Paused")

See the groups.py docstrings for more details on supported fields and behaviors.

get_user_sign_ins(user_id, ctx, days=7) — Get sign-in logs for a user

MFA Tools

get_user_mfa_status(user_id, ctx) — Get MFA status for a user
get_group_mfa_status(group_id, ctx) — Get MFA status for all group members

Device Tools

get_all_managed_devices(filter_os=None) — Get all managed devices (optionally filter by OS)
get_managed_devices_by_user(user_id) — Get all managed devices for a specific user

Conditional Access Policy Tools

get_conditional_access_policies(ctx) — Get all conditional access policies
get_conditional_access_policy_by_id(policy_id, ctx) — Get a single conditional access policy by its ID

Audit Log Tools

get_user_audit_logs(user_id, days=30) — Get all relevant directory audit logs for a user by user_id within the last N days

Password Management Tools

reset_user_password_direct(user_id, password=None, require_change_on_next_sign_in=True, generate_password=False, password_length=12) — Reset a user's password with a specific password value or generate a secure random password

Permissions Helper Tools

suggest_permissions_for_task(task_category, task_name) — Suggest Microsoft Graph permissions for a specific task based on common mappings
list_permission_categories_and_tasks() — List all available categories and tasks for permission suggestions
get_all_graph_permissions() — Get all Microsoft Graph permissions directly from the Microsoft Graph API
search_permissions(search_term, permission_type=None) — Search for Microsoft Graph permissions by keyword

Application Tools

list_applications(ctx, limit=100) — List all applications (app registrations) in the tenant, with paging
get_application_by_id(app_id, ctx) — Get a specific application by its object ID (includes app role assignments and delegated permissions)
create_application(ctx, app_data) — Create a new application (see below for app_data fields)
update_application(app_id, ctx, app_data) — Update an existing application (fields: displayName, signInAudience, tags, identifierUris, web, api, requiredResourceAccess)
delete_application(app_id, ctx) — Delete an application by its object ID

Application Creation/Update Example:

app_data for create_application and update_application should be a dictionary with keys such as:
- displayName (required for create)
- signInAudience (optional)
- tags (optional)
- identifierUris (optional)
- web (optional)
- api (optional)
- requiredResourceAccess (optional)

Service Principal Tools

list_service_principals(ctx, limit=100) — List all service principals in the tenant, with paging
get_service_principal_by_id(sp_id, ctx) — Get a specific service principal by its object ID (includes app role assignments and delegated permissions)
create_service_principal(ctx, sp_data) — Create a new service principal (see below for sp_data fields)
update_service_principal(sp_id, ctx, sp_data) — Update an existing service principal (fields: displayName, accountEnabled, tags, appRoleAssignmentRequired)
delete_service_principal(sp_id, ctx) — Delete a service principal by its object ID

Service Principal Creation/Update Example:

sp_data for create_service_principal and update_service_principal should be a dictionary with keys such as:
- appId (required for create)
- accountEnabled (optional)
- tags (optional)
- appRoleAssignmentRequired (optional)
- displayName (optional)

Example Resource

greeting://{name} — Returns a personalized greeting

Extending the Server

Add new resource modules under resources/ (e.g., groups.py, devices.py).
Register new tools in server.py using the FastMCP @mcp.tool() decorator.
Use the shared GraphClient for all API calls.

Security & Best Practices

Never commit secrets: .env and other sensitive files are gitignored.
Use least privilege: Grant only the necessary Microsoft Graph permissions to your Azure AD app.
Audit & monitor: Use the logging output for troubleshooting and monitoring.

Required Graph API Permissions

API / Permission	Type	Description
AuditLog.Read.All	Application	Read all audit log data
AuthenticationContext.Read.All	Application	Read all authentication context information
DeviceManagementManagedDevices.Read.All	Application	Read Microsoft Intune devices
Directory.Read.All	Application	Read directory data
Group.Read.All	Application	Read all groups
GroupMember.Read.All	Application	Read all group memberships
Group.ReadWrite.All	Application	Create, update, delete groups; manage group members and owners
Policy.Read.All	Application	Read your organization's policies
RoleManagement.Read.Directory	Application	Read all directory RBAC settings
User.Read.All	Application	Read all users' full profiles
User-PasswordProfile.ReadWrite.All	Application	Least privileged permission to update the passwordProfile property
UserAuthenticationMethod.Read.All	Application	Read all users' authentication methods
Application.ReadWrite.All	Application	Create, update, and delete applications (app registrations) and service principals

Advanced: Using with Claude or Cursor

Using with Claude (Anthropic)

To install and run this server as a Claude MCP tool, use:

fastmcp install '/path/to/src/msgraph_mcp_server/server.py' \
  --with msgraph-sdk --with azure-identity --with azure-core --with msgraph-core \
  -f /path/to/.env

Replace /path/to/ with your actual project path.
The -f flag points to your .env file (never commit secrets!).

Using with Cursor

Add the following to your .cursor/mcp.json (do not include actual secrets in version control):

{
  "EntraID MCP Server": {
    "command": "uv",
    "args": [
      "run",
      "--with", "azure-core",
      "--with", "azure-identity",
      "--with", "fastmcp",
      "--with", "msgraph-core",
      "--with", "msgraph-sdk",
      "fastmcp",
      "run",
      "/path/to/src/msgraph_mcp_server/server.py"
    ],
    "env": {
      "TENANT_ID": "<your-tenant-id>",
      "CLIENT_ID": "<your-client-id>",
      "CLIENT_SECRET": "<your-client-secret>"
    }
  }
}

Replace /path/to/ and the environment variables with your actual values.
Never commit real secrets to your repository!

License

MIT

EntraID MCP Server

EntraID MCP Server (Microsoft Graph FastMCP)

Features

Project Structure

Usage

1. Setup

2. Testing & Development

3. Available Tools

User Tools

Group Tools

Sign-in Log Tools

MFA Tools

Device Tools

Conditional Access Policy Tools

Audit Log Tools

Password Management Tools

Permissions Helper Tools

Application Tools

Service Principal Tools

Example Resource

Extending the Server

Security & Best Practices

Required Graph API Permissions

Advanced: Using with Claude or Cursor

Using with Claude (Anthropic)

Using with Cursor

License

EntraID MCP Server (Microsoft Graph FastMCP)

Features

Project Structure

Usage

1. Setup

2. Testing & Development

3. Available Tools

User Tools

Group Tools

Sign-in Log Tools

MFA Tools

Device Tools

Conditional Access Policy Tools

Audit Log Tools

Password Management Tools

Permissions Helper Tools

Application Tools

Service Principal Tools

Example Resource

Extending the Server

Security & Best Practices

Required Graph API Permissions

Advanced: Using with Claude or Cursor

Using with Claude (Anthropic)

Using with Cursor

License