onelogin-mcp

OneLogin MCP 服务

一个 Model Context Protocol 服务，可全面访问 OneLogin API。支持 Claude Desktop、OpenCode 和其他 MCP 客户端管理用户、应用、角色、身份验证和安全设置。

概述

此服务提供多种工具，涵盖一系列受支持的 OneLogin API 端点：

• 身份管理：用户、角色、群组
• 应用：应用、连接器、SAML、OAuth
• 身份验证：MFA、会话、风险规则
• 安全：API 授权
• 配置：品牌、映射
• 运维：事件、报告、速率限制

所有工具都包含详尽的说明，其中涵盖警告、最佳实践和返回数据规范。

演示

https://github.com/user-attachments/assets/512abc44-6bb4-42e4-bb47-c0bc16f29beb

安装

前置条件

• OneLogin API 凭据（OAuth2 客户端 ID 和密钥）
• AI 客户端，例如 OpenCode、Claude Desktop、Copilot CLI 或 Claude Code

设置

选项 1：环境变量（推荐）

直接在 Claude Desktop 配置中设置凭据，无需单独设置。

编辑配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.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"
      }
    }
  }
}

多个环境（区分生产和测试环境）：

{
  "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"
      }
    }
  }
}

可选环境变量：

• ONELOGIN_USE_PREPROD：在预生产环境中设为 "true"
• ONELOGIN_LEGACY_KEY：旧版 API 密钥（很少需要）
• ONELOGIN_SERVER：用于日志记录的服务名称（默认为 "default"）

配置完成后，完全退出并重启 Claude Desktop。

OpenCode 配置

对于 OpenCode 用户，将以下内容添加到 ~/.config/opencode/mcp.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"
      }
    }
  }
}

多个环境：

{
  "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"
      }
    }
  }
}

配置完成后，重启 OpenCode。

选项 2：设置脚本（servers.json）

使用配置文件的替代方法：

1. 安装软件包：

npm install -g @onelogin/onelogin-mcp

2. 配置 OneLogin 凭据：

npx onelogin-mcp-setup

出现提示时，输入 OneLogin 服务详细信息：

• 服务名称（例如 "Production"、"Test"）
• OneLogin 子域名 URL（例如 https://mycompany.onelogin.com）
• OAuth2 客户端 ID 和密钥

配置存储在 ~/.config/onelogin-mcp/servers.json 中。

3. 添加到 Claude Desktop 配置：

编辑配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

单个环境：

{
  "mcpServers": {
    "onelogin": {
      "command": "npx",
      "args": ["-y", "@onelogin/onelogin-mcp"]
    }
  }
}

多个环境（按名称引用服务）：

{
  "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. 完全退出并重启 Claude Desktop。

使用方法

使用自然语言与 OneLogin 交互：

List all users with email ending in @example.com
Get details for user ID 12345
Create a user [email protected] with firstname John, lastname Doe
Assign roles [123, 456] to user 789
Generate MFA token for user 101112
List all SAML apps

Claude 会选择合适的工具、调用 OneLogin API 并呈现结果。

API 覆盖范围

此服务提供 156 个工具，分为 7 大类别：

身份与访问（59 个工具）

• 用户（14）
• 角色（13）
• 权限（11）
• 群组（6）
• 映射（15）

应用（17 个工具）

• 应用（15）
• 连接器（2）

身份验证（21 个工具）

• MFA（10）
• 会话（5）
• SAML（2）
• OAuth 令牌（2）
• 邀请链接（2）

安全（40 个工具）

• 策略（7）
• 风险规则（6）
• 智能钩子（11）
• API 授权（16）

自定义（6 个工具）

• 品牌（6）

监控（9 个工具）

• 事件（2）
• 报告（5）
• 速率限制（2）

账户管理（4 个工具）

• 账户（4）

配置

凭据管理

服务支持两种配置方式：

1. 环境变量（推荐）：在 MCP 客户端配置中设置 ONELOGIN_URL、ONELOGIN_CLIENT_ID 和 ONELOGIN_CLIENT_SECRET（请参阅上文的安装部分）
2. 配置文件：使用 npx onelogin-mcp-setup 将凭据存储在 ~/.config/onelogin-mcp/servers.json 中

环境变量的优先级高于配置文件。完整配置示例请参阅上文的安装部分。

可选环境变量

• ONELOGIN_USE_PREPROD：在预发布环境中设为 "true"
• ONELOGIN_LEGACY_KEY：旧版 API 密钥（很少需要）
• ONELOGIN_SERVER：用于日志记录的服务名称（默认为 "default"），或用于从 servers.json 中选择具名服务

响应格式

所有工具都会返回结构化响应：

{
  "success": true,
  "request_id": "68F194DE-0A0D05A2-55F8-0A0F6C42-01BB-62EAE-0008",
  "status": 200,
  "data": {
    // Tool-specific data
  }
}

request_id 与 HTTP 请求头 x-request-id 相匹配，可用于在 Datadog 和 OneLogin 日志中进行追踪。

故障排除

Claude Desktop 中未显示服务

1. 验证 JSON 配置语法
2. 确保 index.js 使用绝对路径
3. 完全重启 Claude Desktop（退出后重新打开）

“spawn bun ENOENT”错误

Claude 无法找到 Bun 运行时。解决方法：

# 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"]
}

身份验证错误

1. 如果使用环境变量：验证 Claude Desktop 配置中的 ONELOGIN_URL、ONELOGIN_CLIENT_ID 和 ONELOGIN_CLIENT_SECRET
2. 如果使用 servers.json：验证 ~/.config/onelogin-mcp/servers.json 中的凭据
3. 确保 OAuth2 客户端在 OneLogin 管理面板中拥有 API 权限
4. 检查 client_id 和 client_secret 是否适用于 API v2

环境错误

使用环境变量：每个 MCP 服务条目都有自己的凭据——请确认你在 Claude 中连接的是正确的服务实例。

使用 servers.json：检查 Claude Desktop 配置中的 ONELOGIN_SERVER 环境变量是否与 servers.json 中的某个服务名称相匹配。

项目结构

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

开发

添加新工具的指南请参阅 CONTRIBUTING.md。

主要约定：

• 工具描述包含警告、最佳实践和返回数据结构
• 所有模块均导出 tools 数组和 handlers 对象
• 注册表会自动从模块导入项中发现工具

发布

要向 npm 发布新版本：

1. 将更改合并到 main 分支

2. 创建 GitHub Release：

   • 前往 Releases → “Draft a new release”
   • 使用版本号创建新标签（例如，v1.1.0）
   • 设置发布标题（例如，“v1.1.0 - MFA API fixes”）
   • 添加说明更改内容的发布说明
   • 点击“Publish release”

3. 自动发布：GitHub Action 将会：

   • 从发布标签中提取版本号（去掉 v 前缀）
   • 使用新版本号更新 package.json
   • 将包发布到 npm，名称为 @onelogin/onelogin-mcp

版本格式：使用语义化版本（MAJOR.MINOR.PATCH）

• MAJOR：不兼容的 API 更改
• MINOR：新增功能，向后兼容
• PATCH：错误修复，向后兼容

手动发布（如有需要）：

• 前往 Actions → “Publish Package” → “Run workflow”
• 可选择指定版本覆盖值

支持

• GitHub Issues
• OneLogin API 文档
• Model Context Protocol

许可证

MIT