# 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 156 tools organized into 7 major categories:

**Identity & Access** (59 tools)
- Users (14)
- Roles (13)
- Privileges (11)
- Groups (6)
- Mappings (15)

**Applications** (17 tools)
- Apps (15)
- Connectors (2)

**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** (9 tools)
- Events (2)
- Reports (5)
- 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 (2 tools)
│       ├── reports.js          # Analytics (5 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