https://github.com/kapilduraphe/okta-mcp-server
Okta MCP Server
https://github.com/kapilduraphe/okta-mcp-server
Last synced: 2 months ago
JSON representation
Okta MCP Server
- Host: GitHub
- URL: https://github.com/kapilduraphe/okta-mcp-server
- Owner: kapilduraphe
- License: mit
- Created: 2025-02-14T19:18:00.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-03-20T22:15:33.000Z (3 months ago)
- Last Synced: 2025-03-20T23:25:01.878Z (3 months ago)
- Language: TypeScript
- Homepage:
- Size: 19.5 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - Okta - Manages Okta users and groups via a Claude-integrated server (Table of Contents / Security)
- awesome-mcp-servers - Okta - Manages Okta users and groups via a Claude-integrated server (Table of Contents / Security)
README
# Okta MCP Server
This MCP server enables Claude to interact with Okta's user management system, providing user and group management capabilities.
## 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:
### 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
### 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
### 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
## Example Usage in Claude
After setup, you can use commands like:
- "Show me details for user with userId XXXX"
- "What's the status of user [email protected]"
- "When was the last login for user [email protected]"
- "List all users in the marketing department"
- "Find users created in the last month"
- "Show me all the groups in my Okta organization"
- "List groups containing the word 'admin'"
## 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
## 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`
### 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
## 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;
};
}
```
## 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!