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 許可證。