EntraID MCP Server (Microsoft Graph FastMCP)

1# EntraID MCP Server (Microsoft Graph FastMCP)
2 
3This 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.
4 
5## Features
6 
7- **Modular Resource Structure:**
8  - Each resource (users, sign-in logs, MFA, etc.) is implemented in its own module under `src/msgraph_mcp_server/resources/`.
9  - Easy to extend with new resources (e.g., groups, devices).
10- **Centralized Graph Client:**
11  - Handles authentication and client initialization.
12  - Shared by all resource modules.
13- **Comprehensive User Operations:**
14  - Search users by name/email.
15  - Get user by ID.
16  - List all privileged users (directory role members).
17- **Full Group Lifecycle & Membership Management:**
18  - Create, read, update, and delete groups.
19  - Add/remove group members and owners.
20  - Search and list groups and group members.
21- **Application & Service Principal Management:**
22  - List, create, update, and delete applications (app registrations).
23  - List, create, update, and delete service principals.
24  - View app role assignments and delegated permissions for both applications and service principals.
25- **Sign-in Log Operations:**
26  - Query sign-in logs for a user for the last X days.
27- **MFA Operations:**
28  - Get MFA status for a user.
29  - Get MFA status for all members of a group.
30- **Password Management:**
31  - Reset user passwords directly with custom or auto-generated secure passwords.
32  - Option to require password change on next sign-in.
33- **Permissions Helper:**
34  - Suggest appropriate Microsoft Graph permissions for common tasks.
35  - Search and explore available Graph permissions.
36  - Helps implement the principle of least privilege by recommending only necessary permissions.
37- **Error Handling & Logging:**
38  - Consistent error handling and progress reporting via FastMCP context.
39  - Detailed logging for troubleshooting.
40- **Security:**
41  - `.env` and secret files are excluded from version control.
42  - Uses Microsoft best practices for authentication.
43 
44## Project Structure
45 
46```
47src/msgraph_mcp_server/
48├── auth/           # Authentication logic (GraphAuthManager)
49├── resources/      # Resource modules (users, signin_logs, mfa, ...)
50│   ├── users.py            # User operations (search, get by ID, etc.)
51│   ├── signin_logs.py      # Sign-in log operations
52│   ├── mfa.py              # MFA status operations
53│   ├── permissions_helper.py # Graph permissions utilities and suggestions
54│   ├── applications.py       # Application (app registration) operations
55│   ├── service_principals.py # Service principal operations
56│   └── ...                 # Other resource modules
57├── utils/          # Core GraphClient and other ultilities tool, such as password generator..
58├── server.py       # FastMCP server entry point (registers tools/resources)
59├── __init__.py     # Package marker
60```
61 
62## Usage
63 
64### 1. Setup
65- Clone the repo.
66- Create a `config/.env` file with your Azure AD credentials:
67  ```
68  TENANT_ID=your-tenant-id
69  CLIENT_ID=your-client-id
70  CLIENT_SECRET=your-client-secret
71  ```
72- (Optional) Set up certificate-based auth if needed.
73 
74### 2. Testing & Development
75 
76You can test and develop your MCP server directly using the FastMCP CLI:
77 
78```bash
79fastmcp dev '/path/to/src/msgraph_mcp_server/server.py'
80```
81 
82This launches an interactive development environment with the MCP Inspector. For more information and advanced usage, see the [FastMCP documentation](https://github.com/jlowin/fastmcp).
83 
84### 3. Available Tools
85 
86#### User Tools
87- `search_users(query, ctx, limit=10)` — Search users by name/email
88- `get_user_by_id(user_id, ctx)` — Get user details by ID
89- `get_privileged_users(ctx)` — List all users in privileged directory roles
90- `get_user_roles(user_id, ctx)` — Get all directory roles assigned to a user
91- `get_user_groups(user_id, ctx)` — Get all groups (including transitive memberships) for a user
92 
93#### Group Tools
94- `get_all_groups(ctx, limit=100)` — Get all groups (with paging)
95- `get_group_by_id(group_id, ctx)` — Get a specific group by its ID
96- `search_groups_by_name(name, ctx, limit=50)` — Search for groups by display name
97- `get_group_members(group_id, ctx, limit=100)` — Get members of a group by group ID
98- `create_group(ctx, group_data)` — Create a new group (see below for group_data fields)
99- `update_group(group_id, ctx, group_data)` — Update an existing group (fields: displayName, mailNickname, description, visibility)
100- `delete_group(group_id, ctx)` — Delete a group by its ID
101- `add_group_member(group_id, member_id, ctx)` — Add a member (user, group, device, etc.) to a group
102- `remove_group_member(group_id, member_id, ctx)` — Remove a member from a group
103- `add_group_owner(group_id, owner_id, ctx)` — Add an owner to a group
104- `remove_group_owner(group_id, owner_id, ctx)` — Remove an owner from a group
105 
106**Group Creation/Update Example:**
107- `group_data` for `create_group` and `update_group` should be a dictionary with keys such as:
108  - `displayName` (required for create)
109  - `mailNickname` (required for create)
110  - `description` (optional)
111  - `groupTypes` (optional, e.g., `["Unified"]`)
112  - `mailEnabled` (optional)
113  - `securityEnabled` (optional)
114  - `visibility` (optional, "Private" or "Public")
115  - `owners` (optional, list of user IDs)
116  - `members` (optional, list of IDs)
117  - `membershipRule` (required for dynamic groups)
118  - `membershipRuleProcessingState` (optional, "On" or "Paused")
119 
120See the `groups.py` docstrings for more details on supported fields and behaviors.
121 
122#### Sign-in Log Tools
123- `get_user_sign_ins(user_id, ctx, days=7)` — Get sign-in logs for a user
124 
125#### MFA Tools
126- `get_user_mfa_status(user_id, ctx)` — Get MFA status for a user
127- `get_group_mfa_status(group_id, ctx)` — Get MFA status for all group members
128 
129#### Device Tools
130- `get_all_managed_devices(filter_os=None)` — Get all managed devices (optionally filter by OS)
131- `get_managed_devices_by_user(user_id)` — Get all managed devices for a specific user
132 
133#### Conditional Access Policy Tools
134- `get_conditional_access_policies(ctx)` — Get all conditional access policies
135- `get_conditional_access_policy_by_id(policy_id, ctx)` — Get a single conditional access policy by its ID
136 
137#### Audit Log Tools
138- `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
139 
140#### Password Management Tools
141- `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
142 
143#### Permissions Helper Tools
144- `suggest_permissions_for_task(task_category, task_name)` — Suggest Microsoft Graph permissions for a specific task based on common mappings
145- `list_permission_categories_and_tasks()` — List all available categories and tasks for permission suggestions
146- `get_all_graph_permissions()` — Get all Microsoft Graph permissions directly from the Microsoft Graph API
147- `search_permissions(search_term, permission_type=None)` — Search for Microsoft Graph permissions by keyword
148 
149#### Application Tools
150- `list_applications(ctx, limit=100)` — List all applications (app registrations) in the tenant, with paging
151- `get_application_by_id(app_id, ctx)` — Get a specific application by its object ID (includes app role assignments and delegated permissions)
152- `create_application(ctx, app_data)` — Create a new application (see below for app_data fields)
153- `update_application(app_id, ctx, app_data)` — Update an existing application (fields: displayName, signInAudience, tags, identifierUris, web, api, requiredResourceAccess)
154- `delete_application(app_id, ctx)` — Delete an application by its object ID
155 
156**Application Creation/Update Example:**
157- `app_data` for `create_application` and `update_application` should be a dictionary with keys such as:
158  - `displayName` (required for create)
159  - `signInAudience` (optional)
160  - `tags` (optional)
161  - `identifierUris` (optional)
162  - `web` (optional)
163  - `api` (optional)
164  - `requiredResourceAccess` (optional)
165 
166#### Service Principal Tools
167- `list_service_principals(ctx, limit=100)` — List all service principals in the tenant, with paging
168- `get_service_principal_by_id(sp_id, ctx)` — Get a specific service principal by its object ID (includes app role assignments and delegated permissions)
169- `create_service_principal(ctx, sp_data)` — Create a new service principal (see below for sp_data fields)
170- `update_service_principal(sp_id, ctx, sp_data)` — Update an existing service principal (fields: displayName, accountEnabled, tags, appRoleAssignmentRequired)
171- `delete_service_principal(sp_id, ctx)` — Delete a service principal by its object ID
172 
173**Service Principal Creation/Update Example:**
174- `sp_data` for `create_service_principal` and `update_service_principal` should be a dictionary with keys such as:
175  - `appId` (required for create)
176  - `accountEnabled` (optional)
177  - `tags` (optional)
178  - `appRoleAssignmentRequired` (optional)
179  - `displayName` (optional)
180 
181#### Example Resource
182- `greeting://{name}` — Returns a personalized greeting
183 
184## Extending the Server
185- Add new resource modules under `resources/` (e.g., `groups.py`, `devices.py`).
186- Register new tools in `server.py` using the FastMCP `@mcp.tool()` decorator.
187- Use the shared `GraphClient` for all API calls.
188 
189## Security & Best Practices
190- **Never commit secrets:** `.env` and other sensitive files are gitignored.
191- **Use least privilege:** Grant only the necessary Microsoft Graph permissions to your Azure AD app.
192- **Audit & monitor:** Use the logging output for troubleshooting and monitoring.
193 
194## Required Graph API Permissions
195| API / Permission            | Type        | Description                               |
196|-----------------------------|-------------|-------------------------------------------|
197| AuditLog.Read.All           | Application | Read all audit log data                   |
198| AuthenticationContext.Read.All | Application | Read all authentication context information |
199| DeviceManagementManagedDevices.Read.All | Application | Read Microsoft Intune devices |
200| Directory.Read.All          | Application | Read directory data                       |
201| Group.Read.All              | Application | Read all groups                           |
202| GroupMember.Read.All        | Application | Read all group memberships                |
203| Group.ReadWrite.All         | Application | Create, update, delete groups; manage group members and owners |
204| Policy.Read.All             | Application | Read your organization's policies         |
205| RoleManagement.Read.Directory | Application | Read all directory RBAC settings        |
206| User.Read.All               | Application | Read all users' full profiles             |
207| User-PasswordProfile.ReadWrite.All | Application | Least privileged permission to update the passwordProfile property |
208| UserAuthenticationMethod.Read.All | Application | Read all users' authentication methods |
209| Application.ReadWrite.All   | Application | Create, update, and delete applications (app registrations) and service principals |
210 
211**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.
212 
213## Advanced: Using with Claude or Cursor
214 
215### Using with Claude (Anthropic)
216To install and run this server as a Claude MCP tool, use:
217 
218```bash
219fastmcp install '/path/to/src/msgraph_mcp_server/server.py' \
220  --with msgraph-sdk --with azure-identity --with azure-core --with msgraph-core \
221  -f /path/to/.env
222```
223- Replace `/path/to/` with your actual project path.
224- The `-f` flag points to your `.env` file (never commit secrets!).
225 
226### Using with Cursor
227Add the following to your `.cursor/mcp.json` (do **not** include actual secrets in version control):
228 
229```json
230{
231  "EntraID MCP Server": {
232    "command": "uv",
233    "args": [
234      "run",
235      "--with", "azure-core",
236      "--with", "azure-identity",
237      "--with", "fastmcp",
238      "--with", "msgraph-core",
239      "--with", "msgraph-sdk",
240      "fastmcp",
241      "run",
242      "/path/to/src/msgraph_mcp_server/server.py"
243    ],
244    "env": {
245      "TENANT_ID": "<your-tenant-id>",
246      "CLIENT_ID": "<your-client-id>",
247      "CLIENT_SECRET": "<your-client-secret>"
248    }
249  }
250}
251```
252- Replace `/path/to/` and the environment variables with your actual values.
253- **Never commit real secrets to your repository!**
254 
255## License
256 
257MIT
258