Okta MCP Server

[](https://mseep.ai/app/kapilduraphe-okta-mcp-server) # Okta MCP Server This MCP server enables Claude to interact with Okta's user management system, providing comprehensive user and group management capabilities along with onboarding automation. <a href="https://glama.ai/mcp/servers/@kapilduraphe/okta-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@kapilduraphe/okta-mcp-server/badge" alt="Okta Server MCP server" /> </a> ## Prerequisites - Node.js (v16 or higher) - Claude Desktop App - Okta Developer Account - Admin API Token from Okta ## Setup Instructions ### 1. Create an Okta Developer Account - Go to the [Okta Developer Console](https://developer.okta.com/) - Create a new account or sign in to an existing one - Note your Okta domain (e.g., `dev-123456.okta.com`) ### 2. Create an API Token - In the Okta Developer Console, go to Security > API > Tokens - Click "Create Token" - Give your token a meaningful name (e.g., "MCP Server Token") - Copy the token value (you won't be able to see it again) ### 3. Initial Project Setup Install dependencies: ```bash npm install ``` ### 4. Configure Claude Desktop Open your Claude Desktop configuration file: For MacOS: ```bash code ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` For Windows: ```bash code %AppData%\Claude\claude_desktop_config.json ``` Add or update the configuration: ```json { "mcpServers": { "okta": { "command": "node", "args": [ "PATH_TO_PROJECT_DIRECTORY/dist/index.js" ], "env": { "OKTA_ORG_URL": "https://your-domain.okta.com", "OKTA_API_TOKEN": "your-api-token" } } } } ``` Save the file and restart Claude Desktop. ## Available Tools The server provides the following tools: ### User Management #### get_user Retrieves detailed user information from Okta, including: - User Details (ID, Status) - Account Dates (Created, Activated, Last Login, etc.) - Personal Information (Name, Email) - Employment Details - Contact Information - Address - Preferences #### find_users_by_attribute Search users by any profile attribute with advanced filtering: - **Supported attributes**: firstName, lastName, email, manager, department, title, division, organization, employeeNumber, costCenter, userType, city, state - **Search operators**: - `eq` (exact match) - Works for all attributes - `sw` (starts with) - Works for all attributes - `ew` (ends with) - Works for most attributes - `co` (contains) - Works for some attributes (firstName, lastName, email) - `pr` (present/exists) - Works for all attributes (finds users with any value for that attribute) - **Features**: - Uses Okta's native search for optimal performance - Automatic fallback to client-side filtering for unsupported operators - PII masking in search results for sensitive attributes - Status filtering (include/exclude inactive users) - Pagination support with customizable limits #### list_users Lists users from Okta with optional filtering and pagination: - Supports SCIM filter expressions (e.g., 'profile.firstName eq "John"') - Free-form text search across multiple fields - Sorting options (by status, creation date, etc.) - Pagination support with customizable limits #### activate_user Activates a user in Okta: - Option to send activation email - Updates user status to active #### suspend_user Suspends a user in Okta #### unsuspend_user Unsuspends a previously suspended user in Okta #### delete_user Deletes a user from Okta (note: user must be deactivated first) #### get_user_last_location Retrieves the last known location and login information for a user from Okta system logs ### Group Management #### list_groups Lists user groups from Okta with optional filtering and pagination: - Filter expressions for groups (e.g., 'type eq "OKTA_GROUP"') - Free-form text search across group fields - Sorting options (by name, type, etc.) - Pagination support with customizable limits #### create_group Creates a new group in Okta with a name and optional description #### get_group Retrieves detailed information about a specific group #### delete_group Deletes a group from Okta #### assign_user_to_group Assigns a user to a group in Okta #### remove_user_from_group Removes a user from a group in Okta #### list_group_users Lists all users in a specific group with pagination support ### Onboarding Automation (Experimental) > **Note:** The onboarding automation tools are experimental and may be subject to changes or limitations based on Okta's API constraints. Use with caution in production environments. #### bulk_user_import Imports multiple users from a CSV string: - Creates user accounts based on CSV data - Optional activation of users - Optional email notifications - Assignment to default groups #### assign_users_to_groups Assigns multiple users to groups based on attribute mappings: - Maps user attributes (department, title, etc.) to specific groups - Bulk assignment of users based on attributes #### provision_applications Provisions application access for multiple users: - Assigns users to applications - Supports bulk provisioning #### run_onboarding_workflow Runs a complete onboarding workflow for multiple users from CSV data: - User import from CSV - Automatic activation - Group assignment based on attributes - Application provisioning - Welcome email configuration ## Example Usage in Claude After setup, you can use commands like: ### User Management - "Show me details for user with userId XXXX" - "Find all users in the engineering department" - "Search for users with first name starting with 'John'" - "Find users whose email contains 'gmail'" - "Show me all users who have a department assigned" - "List users whose title is 'Manager'" - "What's the status of user john.doe@company.com" - "When was the last login for user jane.smith@organization.com" - "Find users created in the last month" - "Activate user with ID XXXX" - "Suspend user with ID XXXX" - "Delete deactivated user with ID XXXX" - "Where did user XXXX last log in from?" ### Advanced User Searches - "Find all users in the Sales department" → Uses `find_users_by_attribute` with `department eq "Sales"` - "Show me users whose email starts with 'admin'" → Uses `email sw "admin"` - "Find users with any manager assigned" → Uses `manager pr` - "List users whose last name contains 'smith'" → Uses `lastName co "smith"` ### Group Management - "Show me all groups in my Okta organization" - "List groups containing the word 'admin'" - "Create a new group called 'Marketing Team'" - "Get details for group with ID XXXX" - "Delete group with ID XXXX" - "Add user XXXX to group YYYY" - "Remove user XXXX from group YYYY" - "List all users in the 'Finance' group" ### Onboarding Automation - "Import these users from CSV data: [CSV content]" - "Assign users to groups based on their department attribute" - "Provision application access for these 5 users" - "Run a complete onboarding workflow for these new hires: [CSV content]" ## Error Handling The server includes robust error handling for: - User or group not found (404 errors) - API authentication issues - Missing or invalid user profiles - General API errors - CSV parsing issues - User attribute mapping failures - Application provisioning errors - Unsupported search operators (automatic fallback to alternative methods) ## Troubleshooting ### Common Issues **Tools not appearing in Claude:** - Check Claude Desktop logs: `tail -f ~/Library/Logs/Claude/mcp*.log` - Verify all environment variables are set correctly - Ensure the path to index.js is absolute and correct **Authentication Errors:** - Verify your API token is valid - Check if OKTA_ORG_URL includes the full URL with https:// - Ensure your Okta domain is correct **Server Connection Issues:** - Check if the server built successfully - Verify file permissions on build/index.js (should be 755) - Try running the server directly: `node /path/to/build/index.js` **Search Issues:** - Some search operators are not supported for all attributes (e.g., `contains` doesn't work for `department`) - The server automatically falls back to alternative search methods when needed - Check the response message for which search method was used ### Viewing Logs To view server logs: For MacOS/Linux: ```bash tail -n 20 -f ~/Library/Logs/Claude/mcp*.log ``` For Windows: ```powershell Get-Content -Path "$env:AppData\Claude\Logs\mcp*.log" -Wait -Tail 20 ``` ### Environment Variables If you're getting environment variable errors, verify: - `OKTA_ORG_URL`: Should be complete URL (e.g., "https://dev-123456.okta.com") - `OKTA_API_TOKEN`: Should be a valid API token ## Security Considerations - Keep your API token secure - Don't commit credentials to version control - Use environment variables for sensitive data - Regularly rotate API tokens - Monitor API usage in Okta Admin Console - Implement rate limiting for API calls - Use minimum required permissions for API token - PII masking is enabled for sensitive search parameters ## Search Operator Compatibility Different Okta attributes support different search operators: | Attribute Type | eq | sw | ew | co | pr | |----------------|----|----|----|----|----| | firstName, lastName | ✅ | ✅ | ✅ | ✅ | ✅ | | email, login | ✅ | ✅ | ✅ | ✅ | ✅ | | department, title | ✅ | ✅ | ❌ | ❌* | ✅ | | division, organization | ✅ | ✅ | ❌ | ❌* | ✅ | | All attributes | ✅ | ✅ | ⚠️ | ⚠️ | ✅ | *❌ = Not supported, ⚠️ = May not be supported for all attributes > **Note:** When an operator is not supported, the server automatically falls back to client-side filtering for compatibility. ## Types The server includes TypeScript interfaces for Okta user and group data: ```typescript interface OktaUserProfile { login: string; email: string; secondEmail?: string; firstName: string; lastName: string; displayName: string; nickName?: string; organization: string; title: string; division: string; department: string; employeeNumber: string; userType: string; costCenter: string; mobilePhone?: string; primaryPhone?: string; streetAddress: string; city: string; state: string; zipCode: string; countryCode: string; preferredLanguage: string; profileUrl?: string; } interface OktaUser { id: string; status: string; created: string; activated: string; lastLogin: string; lastUpdated: string; statusChanged: string; passwordChanged: string; profile: OktaUserProfile; } interface OktaGroup { id: string; created: string; lastUpdated: string; lastMembershipUpdated: string; type: string; objectClass: string[]; profile: { name: string; description: string; }; } ``` ## CSV Format for Onboarding When using the bulk import or onboarding workflow tools, your CSV should include these headers: - `firstName` (required) - `lastName` (required) - `email` (required) - `department` (optional) - `title` (optional) - `mobilePhone` (optional) Example: ```csv firstName,lastName,email,department,title,mobilePhone John,Doe,john.doe@example.com,Engineering,Senior Developer,+1-555-123-4567 Jane,Smith,jane.smith@example.com,Marketing,Director,+1-555-987-6543 ``` ## License MIT License - See LICENSE file for details. ## Support If you encounter any issues: - Check the troubleshooting section above - Review Claude Desktop logs - Examine the server's error output - Check Okta's developer documentation Note: PRs welcome!