io.github.onelogin/onelogin-mcp
MCP server for OneLogin API - manage users, apps, roles, and authentication
Open source Open in the app JSON README (API)
About
MCP server for OneLogin API - manage users, apps, roles, and authentication
Details
- Kind
- MCP servers
- Topic
- Security & identity
- Publisher
- onelogin
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.2.0
- Stars
- 5
- Forks
- 2
- Last push
- 2026-08-25T22:03:35Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:00:58
- Updated
- 2026-08-29 04:00:58
- Origin id
io.github.onelogin/onelogin-mcp
README
# OneLogin MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io) server providing comprehensive access to the OneLogin API. Enables Claude Desktop, OpenCode, and other MCP clients to manage users, apps, roles, authentication, and security settings.
## Overview
This server provides tools covering a comprehensive set of supported OneLogin API endpoints:
- **Identity Management**: Users, roles, groups
- **Applications**: Apps, connectors, SAML, OAuth
- **Authentication**: MFA, sessions, risk rules
- **Security**: API authorization
- **Configuration**: Brands, mappings
- **Operations**: Events, reports, rate limits
All tools include comprehensive descriptions with warnings, best practices, and return data specifications.
## Demo
https://github.com/user-attachments/assets/512abc44-6bb4-42e4-bb47-c0bc16f29beb
## Installation
### Prerequisites
- OneLogin API credentials (OAuth2 client ID and secret)
- An AI client such as [OpenCode](https://opencode.ai), [Claude Desktop](https://claude.ai/download), [Copilot CLI](https://github.com/features/copilot/cli/), or [Claude Code](https://www.claude.com/product/claude-code)
### Setup
#### Option 1: Environment Variables (Recommended)
Configure credentials directly in Claude Desktop config - no separate setup required.
Edit the config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
**Single environment:**
```json
{
"mcpServers": {
"onelogin": {
"command": "npx",
"args": ["-y", "@onelogin/onelogin-mcp"],
"env": {
"ONELOGIN_URL": "https://mycompany.onelogin.com",
"ONELOGIN_CLIENT_ID": "your_client_id",
"ONELOGIN_CLIENT_SECRET": "your_client_secret"
}
}
}
}
```
**Multiple environments** (production/test separation):
```json
{
"mcpServers": {
"onelogin-prod": {
"command": "npx",
"args": ["-y", "@onelogin/onelogin-mcp"],
"env": {
"ONELOGIN_URL": "https://company.onelogin.com",
"ONELOGIN_CLIENT_ID": "prod_client_id",
"ONELOGIN_CLIENT_SECRET": "prod_secret"
}
},
"onelogin-test": {
"command": "npx",
"args": ["-y", "@onelogin/onelogin-mcp"],
"env": {
"ONELOGIN_URL": "https://company-test.onelogin.com",
"ONELOGIN_CLIENT_ID": "test_client_id",
"ONELOGIN_CLIENT_SECRET": "test_secret"
}
}
}
}
```
**Optional environment variables:**
- `ONELOGIN_USE_PREPROD`: Set to `"true"` for preprod environments
- `ONELOGIN_LEGACY_KEY`: Legacy API key (rarely needed)
- `ONELOGIN_SERVER`: Server name for logging (defaults to "default")
Restart Claude Desktop completely after configuration.
#### OpenCode Configuration
For [OpenCode](https://opencode.ai) users, add to `~/.config/opencode/mcp.json`:
**Single environment:**
```json
{
"mcpServers": {
"onelogin": {
"command": "npx",
"args": ["-y", "@onelogin/onelogin-mcp"],
"env": {
"ONELOGIN_URL": "https://mycompany.onelogin.com",
"ONELOGIN_CLIENT_ID": "your_client_id",
"ONELOGIN_CLIENT_SECRET": "your_client_secret"
}
}
}
}
```
**Multiple environments:**
```json
{
"mcpServers": {
"onelogin-prod": {
"command": "npx",
"args": ["-y", "@onelogin/onelogin-mcp"],
"env": {
"ONELOGIN_URL": "https://company.onelogin.com",
"ONELOGIN_CLIENT_ID": "prod_client_id",
"ONELOGIN_CLIENT_SECRET": "prod_secret"
}
},
"onelogin-test": {
"command": "npx",
"args": ["-y", "@onelogin/onelogin-mcp"],
"env": {
"ONELOGIN_URL": "https://company-test.onelogin.com",
"ONELOGIN_CLIENT_ID": "test_client_id",
"ONELOGIN_CLIENT_SECRET": "test_secret"
}
}
}
}
```
Restart OpenCode after configuration.
#### Option 2: Setup Script (servers.json)
Alternative method using a configuration file:
1. Install the package:
```bash
npm install -g @onelogin/onelogin-mcp
```
2. Configure OneLogin credentials:
```bash
npx onelogin-mcp-setup
```
Enter your OneLogin server details when prompted:
- Server name (e.g., "Production", "Test")
- OneLogin subdomain URL (e.g., `https://mycompany.onelogin.com`)
- OAuth2 client ID and secret
Configuration is stored in `~/.config/onelogin-mcp/servers.json`.
3. Add to Claude Desktop config:
Edit the config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
**Single environment:**
```json
{
"mcpServers": {
"onelogin": {
"command": "npx",
"args": ["-y", "@onelogin/onelogin-mcp"]
}
}
}
```
**Multiple environments** (reference servers by name):
```json
{
"mcpServers": {
"onelogin-prod": {
"command": "npx",
"args": ["-y", "@onelogin/onelogin-mcp"],
"env": {
"ONELOGIN_SERVER": "Production"
}
},
"onelogin-test": {
"command": "npx",
"args": ["-y", "@onelogin/onelogin-mcp"],
"env": {
"ONELOGIN_SERVER": "Test"
}
}
}
}
```
4. Restart Claude Desktop completely.
## Usage
Use natural language to interact with OneLogin:
```
List all users with email ending in @example.com
Get details for user ID 12345
Create a user john.doe@example.com with firstname John, lastname Doe
Assign roles [123, 456] to user 789
Generate MFA token for user 101112
List all SAML apps
```
Claude will select the appropriate tool, call the OneLogin API, and present results.
## API Coverage
This server provides 155 tools organized into 7 major categories:
**Identity & Access** (59 tools)
- Users (14)
- Roles (13)
- Privileges (11)
- Groups (6)
- Mappings (15)
**Applications** (18 tools)
- Apps (15)
- Connectors (3)
**Authentication** (21 tools)
- MFA (10)
- Sessions (5)
- SAML (2)
- OAuth Tokens (2)
- Invite Links (2)
**Security** (40 tools)
- Policies (7)
- Risk Rules (6)
- Smart Hooks (11)
- API Authorization (16)
**Customization** (6 tools)
- Brands (6)
**Monitoring** (7 tools)
- Events (2)
- Reports (3)
- Rate Limits (2)
**Account Management** (4 tools)
- Accounts (4)
## Configuration
### Credential Management
The server supports two configuration methods:
1. **Environment Variables** (recommended): Set `ONELOGIN_URL`, `ONELOGIN_CLIENT_ID`, and `ONELOGIN_CLIENT_SECRET` in your MCP client config (see Installation above)
2. **Configuration File**: Use `npx onelogin-mcp-setup` to store credentials in `~/.config/onelogin-mcp/servers.json`
Environment variables take precedence over the configuration file. See the Installation section above for complete configuration examples.
### Optional Environment Variables
- `ONELOGIN_USE_PREPROD`: Set to `"true"` for preprod environments
- `ONELOGIN_LEGACY_KEY`: Legacy API key (rarely needed)
- `ONELOGIN_SERVER`: Server name for logging (defaults to "default") or to select a named server from servers.json
## Response Format
All tools return structured responses:
```json
{
"success": true,
"request_id": "68F194DE-0A0D05A2-55F8-0A0F6C42-01BB-62EAE-0008",
"status": 200,
"data": {
// Tool-specific data
}
}
```
The `request_id` matches the `x-request-id` HTTP header for tracing in Datadog and OneLogin logs.
## Troubleshooting
### Server not appearing in Claude Desktop
1. Verify JSON config syntax
2. Ensure absolute path to `index.js`
3. Restart Claude Desktop completely (quit and reopen)
### "spawn bun ENOENT" error
Claude cannot find the Bun runtime. Solutions:
```bash
# Verify Bun is installed
which bun
# If not found, install Bun
curl -fsSL https://bun.sh/install | bash
# Or use full path in config
{
"command": "/Users/yourname/.bun/bin/bun",
"args": ["run", "/path/to/index.js"]
}
```
### Authentication errors
1. If using environment variables: Verify `ONELOGIN_URL`, `ONELOGIN_CLIENT_ID`, and `ONELOGIN_CLIENT_SECRET` in Claude Desktop config
2. If using servers.json: Verify credentials in `~/.config/onelogin-mcp/servers.json`
3. Ensure OAuth2 client has API permissions in OneLogin admin panel
4. Check client_id and client_secret are for API v2
### Wrong environment
**Using environment variables**: Each MCP server entry has its own credentials - verify you're talking to the correct server instance in Claude.
**Using servers.json**: Check the `ONELOGIN_SERVER` environment variable in Claude Desktop config matches a server name in `servers.json`.
## Project Structure
```
onelogin-mcp/
├── index.js # MCP server entry point
├── setup.js # Interactive credential setup
├── lib/
│ ├── config.js # Credential management
│ ├── onelogin-api.js # OAuth2 client with token caching
│ └── tools/
│ ├── registry.js # Tool registry and dispatcher
│ ├── users.js # User management (14 tools)
│ ├── roles.js # Role management (13 tools)
│ ├── privileges.js # Privilege management (11 tools)
│ ├── apps.js # App management (15 tools)
│ ├── mfa.js # MFA management (10 tools)
│ ├── mappings.js # User mappings (15 tools)
│ ├── smart-hooks.js # Smart Hooks (11 tools)
│ ├── policies.js # Security policies (7 tools)
│ ├── risk-rules.js # Risk rules (6 tools)
│ ├── api-authorization.js # OAuth scopes (16 tools)
│ ├── sessions.js # Session tokens (5 tools)
│ ├── brands.js # Branding (6 tools)
│ ├── connectors.js # App catalog (3 tools)
│ ├── reports.js # Analytics (3 tools)
│ ├── rate-limits.js # API throttling (2 tools)
│ ├── saml.js # SAML assertions (2 tools)
│ ├── invite-links.js # Password resets (2 tools)
│ ├── oauth-tokens.js # OAuth tokens (2 tools)
│ ├── events.js # Audit logs (2 tools)
│ ├── groups.js # User groups (6 tools)
│ └── accounts.js # Child accounts (4 tools)
├── package.json
├── CONTRIBUTING.md
├── PROGRESS.md
└── README.md
```
## Development
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding new tools.
Key conventions:
- Tool descriptions include warnings, best practices, and return data structure
- All modules export `tools` array and `handlers` object
- Registry auto-discovers tools from module imports
## Releasing
To publish a new version to npm:
1. **Merge your changes** to the `main` branch
2. **Create a GitHub Release**:
- Go to [Releases](https://github.com/onelogin/onelogin-mcp/releases) → "Draft a new release"
- Create a new tag with the version (e.g., `v1.1.0`)
- Set the release title (e.g., "v1.1.0 - MFA API fixes")
- Add release notes describing the changes
- Click "Publish release"
3. **Automatic Publishing**: The GitHub Action will:
- Extract the version from the release tag (strips `v` prefix)
- Update `package.json` with the new version
- Publish to npm under `@onelogin/onelogin-mcp`
**Version Format**: Use semantic versioning (`MAJOR.MINOR.PATCH`)
- `MAJOR`: Breaking API changes
- `MINOR`: New features, backward compatible
- `PATCH`: Bug fixes, backward compatible
**Manual Publishing** (if needed):
- Go to Actions → "Publish Package" → "Run workflow"
- Optionally specify a version override
## Support
- [GitHub Issues](https://github.com/onelogin/onelogin-mcp/issues)
- [OneLogin API Documentation](https://developers.onelogin.com/api-docs)
- [Model Context Protocol](https://modelcontextprotocol.io)
## License
MIT