Onelogin MCP

🚀 OneLogin MCP 服务器

OneLogin MCP 服务器是一个基于 模型上下文协议 的服务器，它提供了对 OneLogin API 的全面访问。借助该服务器，Claude Desktop、OpenCode 等 MCP 客户端能够轻松管理用户、应用程序、角色、认证和安全设置等。

🚀 快速开始

本服务器提供了一系列工具，涵盖了 OneLogin API 所支持的各类端点，具体如下：

• 身份管理：用户、角色、用户组
• 应用程序：应用、连接器、SAML、OAuth
• 认证：多因素认证（MFA）、会话、风险规则
• 安全：API 授权
• 配置：品牌、映射
• 操作：事件、报告、速率限制

所有工具都配有详细的描述，包含警告信息、最佳实践和返回数据规范。

演示地址

点击查看

📦 安装指南

前提条件

• 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 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 将选择合适的工具，调用 OneLogin API 并展示结果。

📚 详细文档

API 覆盖范围

本服务器提供 148 个工具，分为 6 大类：

• 身份与访问（59 个工具）
  • 用户（14 个）
  • 角色（13 个）
  • 权限（11 个）
  • 用户组（6 个）
  • 映射（15 个）
• 应用程序（18 个工具）
  • 应用（15 个）
  • 连接器（3 个）
• 认证（21 个工具）
  • 多因素认证（MFA）（10 个）
  • 会话（5 个）
  • SAML（2 个）
  • OAuth 令牌（2 个）
  • 邀请链接（2 个）
• 安全（37 个工具）
  • 风险规则（6 个）
  • 智能钩子（10 个）
  • API 授权（21 个）
• 定制（6 个工具）
  • 品牌（6 个）
• 监控（7 个工具）
  • 事件（2 个）
  • 报告（3 个）
  • 速率限制（2 个）

配置

凭证管理

服务器支持两种配置方法：

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": {
    // 特定工具的数据
  }
}

request_id 与 x-request-id HTTP 标头匹配，用于在 Datadog 和 OneLogin 日志中进行跟踪。

故障排除

服务器未在 Claude Desktop 中显示

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

"spawn bun ENOENT" 错误

Claude 找不到 Bun 运行时。解决方案如下：

# 验证 Bun 是否安装
which bun

# 如果未找到，安装 Bun
curl -fsSL https://bun.sh/install | bash

# 或者在配置中使用完整路径
{
  "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 服务器入口点
├── setup.js                    # 交互式凭证设置
├── lib/
│   ├── config.js               # 凭证管理
│   ├── onelogin-api.js         # 带有令牌缓存的 OAuth2 客户端
│   └── tools/
│       ├── registry.js         # 工具注册表和调度器
│       ├── users.js            # 用户管理（10 个工具）
│       ├── roles.js            # 角色管理（13 个工具）
│       ├── privileges.js       # 权限管理（11 个工具）
│       ├── apps.js             # 应用管理（7 个工具）
│       ├── mfa.js              # 多因素认证（MFA）管理（11 个工具）
│       ├── mappings.js         # 用户映射（14 个工具）
│       ├── smart-hooks.js      # 智能钩子（8 个工具）
│       ├── risk-rules.js       # 风险规则（6 个工具）
│       ├── api-authorization.js # OAuth 范围（17 个工具）
│       ├── sessions.js         # 会话令牌（5 个工具）
│       ├── brands.js           # 品牌（6 个工具）
│       ├── connectors.js       # 应用目录（3 个工具）
│       ├── reports.js          # 分析（3 个工具）
│       ├── rate-limits.js      # API 限流（2 个工具）
│       ├── saml.js             # SAML 断言（2 个工具）
│       ├── invite-links.js     # 密码重置（2 个工具）
│       ├── oauth-tokens.js     # OAuth 令牌（2 个工具）
│       ├── events.js           # 审计日志（2 个工具）
│       └── groups.js           # 用户组（6 个工具）
├── package.json
├── CONTRIBUTING.md
├── PROGRESS.md
└── README.md

开发

有关添加新工具的指南，请参阅 CONTRIBUTING.md。 关键约定：

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

发布

要将新版本发布到 npm，请执行以下步骤：

1. 合并更改：将更改合并到 main 分支
2. 创建 GitHub 版本：
   • 转到 Releases → "Draft a new release"
   • 创建一个新标签，指定版本号（例如，v1.1.0）
   • 设置版本标题（例如，"v1.1.0 - MFA API 修复"）
   • 添加版本说明，描述更改内容
   • 点击 "Publish release"
3. 自动发布：GitHub Action 将执行以下操作：
   • 从版本标签中提取版本号（去除 v 前缀）
   • 使用新版本更新 package.json
   • 将其发布到 npm 的 @onelogin/onelogin-mcp 下

版本格式：使用语义化版本控制 (MAJOR.MINOR.PATCH)

• MAJOR：API 发生重大更改
• MINOR：添加新功能，向后兼容
• PATCH：修复 bug，向后兼容

手动发布（如有需要）：

• 转到 Actions → "Publish Package" → "Run workflow"
• 可选择指定版本覆盖

支持

• GitHub 问题
• OneLogin API 文档
• 模型上下文协议

📄 许可证

本项目采用 MIT 许可证。