Workspace ONE UEM MCP Server

# Workspace ONE UEM MCP Server A Model Context Protocol (MCP) server that provides access to commonly used Workspace ONE UEM (Unified Endpoint Management) APIs. This server enables AI assistants to interact with your Workspace ONE UEM environment for device management, user administration, and system operations. ## Overview Workspace ONE UEM (formerly AirWatch) is VMware's enterprise mobility management solution. This MCP server exposes the most commonly used APIs through a standardized interface, making it easy to automate device management tasks, query device information, and manage users. ### Included API Categories - **Device Management (MDM)**: Search devices, get details, send commands, manage compliance - **User Management**: Search and manage users, view user devices - **Organization Groups**: Manage organizational structure - **Tags**: Categorize and organize devices - **Applications (MAM)**: Search and manage applications - **Smart Groups**: Work with dynamic device groups - **Events & Audit Logs**: Track system events and changes ## Features ✅ **25+ commonly used APIs** covering the most frequent Workspace ONE UEM operations ✅ **OAuth2 & Basic Auth** support for secure authentication ✅ **Automatic token refresh** for OAuth authentication ✅ **Bulk operations** for efficient multi-device management ✅ **Comprehensive error handling** with clear error messages ✅ **Well-documented tools** with examples and parameter descriptions ## Prerequisites - Python 3.10 or higher - Workspace ONE UEM environment (SaaS or on-premise) - API credentials (see Setup section) - Claude Desktop or compatible MCP client ## Installation 1. **Clone or download this repository** ```bash cd /path/to/your/projects git clone <repository-url> cd workspace-one-uem-mcp ``` 2. **Install dependencies** ```bash pip install -r requirements.txt ``` ## Setup ### 1. Generate API Credentials #### Option A: OAuth Authentication (Recommended) OAuth is the most secure method and is recommended for production use. 1. Log in to your Workspace ONE UEM console 2. Navigate to **Groups & Settings > Configurations** 3. Search for "OAuth" in the search box 4. Click **Add** to create a new OAuth client 5. Fill in the details: - **Name**: MCP Server (or any descriptive name) - **Description**: API access for MCP server - **Organization Group**: Select the appropriate OG - **Role**: Select a role with appropriate API permissions - **Status**: Enabled 6. Click **Save** 7. **Important**: Copy the **Client ID** and **Client Secret** immediately (you can't retrieve the secret later) #### Option B: Basic Authentication For testing or simpler setups, you can use basic authentication: 1. Create a dedicated admin user in Workspace ONE UEM 2. Assign appropriate role permissions for API access 3. Use the username and password in configuration ### 2. Get Your API Key (Tenant Code) 1. Log in to Workspace ONE UEM console 2. Navigate to **Groups & Settings > All Settings > System > Advanced > API > REST API** 3. Make sure you're in the Customer OG or below 4. Copy the **API Key** (also called Tenant Code) 5. Also note your **REST API URL** hostname (e.g., `cn1506.awmdm.com`) ### 3. Determine Your OAuth Token URL Based on your region, use the appropriate token URL: - **North America**: `https://na.uemauth.vmwservices.com/connect/token` - **Europe**: `https://eur.uemauth.vmwservices.com/connect/token` - **Asia Pacific (Sydney)**: `https://apac.uemauth.vmwservices.com/connect/token` See the [Workspace ONE UEM OAuth KB article](https://kb.omnissa.com/s/article/2960893) for details. ### 4. Configure Environment Variables 1. Copy the example environment file: ```bash cp env.example .env ``` 2. Edit `.env` and fill in your values: ```bash # Required WS1_UEM_BASE_URL=https://your-instance.awmdm.com WS1_UEM_API_KEY=your-api-key-here # For OAuth (recommended) WS1_UEM_CLIENT_ID=your-client-id WS1_UEM_CLIENT_SECRET=your-client-secret WS1_UEM_TOKEN_URL=https://na.uemauth.vmwservices.com/connect/token # OR for Basic Auth WS1_UEM_USERNAME=admin@company.com WS1_UEM_PASSWORD=your-password ``` ### 5. Configure Claude Desktop Add this server to your Claude Desktop configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "workspace-one-uem": { "command": "python", "args": ["/absolute/path/to/workspace-one-uem-mcp/server.py"], "env": { "WS1_UEM_BASE_URL": "https://your-instance.awmdm.com", "WS1_UEM_API_KEY": "your-api-key-here", "WS1_UEM_CLIENT_ID": "your-client-id", "WS1_UEM_CLIENT_SECRET": "your-client-secret", "WS1_UEM_TOKEN_URL": "https://na.uemauth.vmwservices.com/connect/token" } } } } ``` Alternatively, if you're using the `.env` file: ```json { "mcpServers": { "workspace-one-uem": { "command": "python", "args": ["/absolute/path/to/workspace-one-uem-mcp/server.py"] } } } ``` 6. **Restart Claude Desktop** to load the new configuration ## Usage Examples Once configured, you can ask Claude to interact with your Workspace ONE UEM environment: ### Device Management ``` "Find all Apple devices in our UEM console" "Get details for device with serial number C02ABC123" "Send a device query command to device with serial number C02ABC123" "Lock all devices with serial numbers: SN001, SN002, SN003" "Show me all devices that haven't been seen in the last 30 days" "Get compliance status for device with UDID 12345678-ABCD..." ``` ### User Management ``` "Find user with email john.doe@company.com" "Show me all devices enrolled by user ID 12345" "List all users in organization group 789" ``` ### Tags and Organization ``` "Get all available tags in organization group 123" "Add tag ID 456 to device ID 789" "Show me all smart groups" "List all devices in smart group 'Corporate iPhones'" ``` ### Applications ``` "Search for Microsoft Teams app" "Show me all apps installed on device ID 12345" "Find all apps for the Apple platform" ``` ### Events and Audit ``` "Show me recent events for device ID 12345" "Search for all device-related events from January 2024" "Get audit logs for admin activities in the last week" ``` ## Available Tools The server provides 25+ tools organized by category: ### Device Management - `search_devices` - Search for devices with various filters - `get_device_details` - Get comprehensive device information - `send_device_command` - Send commands (lock, wipe, query, etc.) - `bulk_device_command` - Send commands to multiple devices - `get_device_compliance` - Check device compliance status - `get_device_profiles` - View assigned profiles - `get_device_apps` - List installed applications - `get_device_events` - View device event history ### User Management - `search_users` - Search for users - `get_user_details` - Get user information - `get_user_devices` - View user's enrolled devices ### Organization Groups - `search_organization_groups` - Search OGs - `get_organization_group_details` - Get OG details ### Tags - `get_tags` - List available tags - `add_device_tag` - Tag a device - `remove_device_tag` - Remove a tag from device ### Applications - `search_apps` - Search applications ### Smart Groups - `get_smart_groups` - List smart groups - `get_smart_group_devices` - Get devices in a smart group ### System - `search_events` - Search system events - `get_api_version` - Verify API connectivity ## Security Best Practices 1. **Use OAuth**: OAuth authentication is more secure than basic auth 2. **Least Privilege**: Create a dedicated API role with only required permissions 3. **Rotate Credentials**: Regularly rotate API keys and OAuth secrets 4. **Secure Storage**: Never commit `.env` files with real credentials to version control 5. **Monitor Usage**: Review audit logs for API activities ## Troubleshooting ### Authentication Issues **Error: 401 Unauthorized** - Verify your API key, client ID, and client secret are correct - Ensure your OAuth client is enabled in UEM console - Check that your token URL matches your region **Error: 403 Forbidden** - Verify the API role has appropriate permissions - Check organization group access for the admin/OAuth client ### Connection Issues **Error: Connection refused** - Verify the BASE_URL is correct (no trailing slash) - Check network connectivity to your UEM instance - Verify firewall rules allow outbound HTTPS ### API Version Issues Some endpoints may require specific API versions. The server defaults to version 2, but some older endpoints may require version 1. Check the Workspace ONE UEM API documentation at `https://your-instance.awmdm.com/api/help` for specific version requirements. ## API Documentation For complete API documentation, visit your UEM instance's API help page: ``` https://your-instance.awmdm.com/api/help ``` This provides: - Complete API reference - Request/response examples - Required parameters - API version information ## Common API Endpoints The server implements these commonly used endpoints: | Category | Endpoint | Purpose | |----------|----------|---------| | Devices | `/api/mdm/devices/search` | Search for devices | | Devices | `/api/mdm/devices` | Get device details | | Devices | `/api/mdm/devices/commands` | Send device commands | | Devices | `/api/mdm/devices/commands/bulk` | Bulk device commands | | Users | `/api/system/users/search` | Search users | | Users | `/api/system/users/{id}/devices` | Get user's devices | | Groups | `/api/system/groups/search` | Search organization groups | | Tags | `/api/system/groups/{id}/tags` | Manage tags | | Apps | `/api/mam/apps/search` | Search applications | | Smart Groups | `/api/mdm/smartgroups/search` | List smart groups | | Events | `/api/system/events/search` | Search events | ## Contributing Contributions are welcome! If you find commonly used APIs that aren't included, please: 1. Verify they're frequently used in Workspace ONE UEM environments 2. Add them following the existing pattern 3. Include comprehensive docstrings with examples 4. Test with both OAuth and Basic Auth ## License [Add your license here] ## Support - **Workspace ONE UEM Documentation**: https://docs.omnissa.com/bundle/WorkspaceONE-UEM - **API Reference**: https://your-instance.awmdm.com/api/help - **Omnissa Community**: https://communities.omnissa.com/ ## Disclaimer This is an unofficial MCP server and is not affiliated with or supported by VMware/Omnissa. Use at your own risk. Always test in a non-production environment first.