delinea-mcp

DelineaMCP

用於 Delinea Secret Server 和 Platform API 的 MCP 伺服器

---

最新消息

• 2026年8月11日 — MCP 協定 v2（規範修訂版 2026-07-28，可串流 HTTP）和實驗性 StrongDM API 支援已推出 — 請參閱版本說明。
• 2026年8月11日 — 我們是「LLM 無法看見秘密」保險庫使用案例的原始提供者 — 請小心仿冒者 ;)

---

功能特色

• 自動對 Secret Server 進行驗證
• 廣泛的 Secret Server 工具集，用於管理資料夾、秘密、使用者、群組和角色。包含收件匣和存取請求輔助工具，以及編碼代理工具。
• ChatGPT 相容工具（search 和 fetch），用於受控的 AI 互動。
• 可選的 Delinea Platform 使用者管理工具
• 可選的實驗性 StrongDM (SDM) 工具 — 存取授予、權限稽核、使用者/角色生命週期、健康與活動報告（請參閱 docs/strongdm.md；使用 pip install "delinea-mcp[strongdm]" 安裝）
• 可串流 HTTP（/mcp）、舊版伺服器發送事件（/mcp/sse）和 STDIO 傳輸
• 依照 MCP 規範，使用動態用戶端註冊的 OAuth 2.0
• 支援安全連線的 TLS
• 開箱即用的 Docker 映像檔和開發伺服器進入點
• 已與 ChatGPT、Claude Desktop、遠端 Claude 連接器、VSCode Copilot 和 openwebui 進行測試

安裝

[!NOTE]

此專案使用 uv（https://github.com/astral-sh/uv），但如果您希望在沒有此工具的情況下執行指令，您可以視需要照常執行 pip 和 venv 指令。

• 安裝 Uv
• 初始化專案：uv pip sync requirements.txt
• 使用 uv run server.py --config config.json

組態設定

密碼等秘密繼續來自環境變數。請在您的 shell 環境中提供 DELINEA_PASSWORD。選用功能依賴其他變數，例如 AZURE_OPENAI_KEY 或 PLATFORM_SERVICE_PASSWORD。

非秘密參數屬於 config.json：

{
  "delinea_username": "<username>",
  "delinea_base_url": "https://your-secret-server/SecretServer",
  "platform_hostname": "<tenant>.secureplatform.io",
  "platform_service_account": "<service_account>",
  "platform_tenant_id": "<tenant_id>",
  "azure_openai_endpoint": "https://example.openai.azure.com/",
  "azure_openai_deployment": "<deployment_name>",
  "auth_mode": "none",
  "transport_mode": "stdio",
  "chatgpt_disable_scope_checks": false,
  "port": 8000,
  "debug": false,
  "external_hostname": null,
  "ssl_keyfile": null,
  "ssl_certfile": null,
  "registration_psk": null,
  "jwt_key_path": ".cache/jwt.json",
  "oauth_db_path": ".cache/oauth.db",
  "enabled_tools": []
}

對於 Secret Server Cloud，請直接使用雲端 URL，不要加 /SecretServer。指定 ssl_keyfile 和 ssl_certfile 以啟用 HTTPS。對於 Let's Encrypt，請使用 privkey.pem 和 fullchain.pem 檔案。

組態檔案支援以下鍵：

• delinea_username - Secret Server 使用者名稱。必須是具有執行所需任務權限的程式化使用者。
• delinea_base_url - 您的 Secret Server 實例的基礎 URL。
• platform_hostname - Platform 租用戶主機名稱（啟用 Platform 工具）。
• platform_service_account - 與 Platform API 搭配使用的服務帳戶。
• platform_tenant_id - Platform API 請求的租用戶 ID。
• strongdm_api_host - StrongDM 控制平面（預設為 app.strongdm.com:443；提供英國/歐盟變體）。憑證來自 SDM_API_ACCESS_KEY / SDM_API_SECRET_KEY 環境變數；請參閱 docs/strongdm.md。
• azure_openai_endpoint - Azure OpenAI 端點。僅在您想要自動產生報告時啟用（大多數代理程式可以自行產生報告 SQL，所以除非需要，否則不要啟用）。
• azure_openai_deployment - Azure OpenAI 的部署名稱。
• auth_mode - 驗證模式（none 或 oauth）。OAuth 顯然不適用於 stdio 傳輸。
• transport_mode - 命令列使用 stdio，HTTP 使用 sse。在 sse 模式下，伺服器同時在 /mcp 提供可串流 HTTP 端點（目前的 MCP 傳輸，服務協定修訂版 2024-11-05 至 2026-07-28），並在 /mcp/sse + /messages/ 提供舊版 HTTP+SSE 端點。
• streamable_http_stateless - 預設為 true；在沒有伺服器端工作階段的情況下執行 /mcp（建議用於遠端連接器）。設定 false 以啟用基於工作階段的操作和獨立 GET 串流。
• streamable_http_json_response - 預設為 true；在 /mcp 上以純 JSON 回應，而非 SSE 框架回應。
• chatgpt_disable_scope_checks - 跳過 ChatGPT 請求的範圍驗證。僅在連線 ChatGPT 遇到問題時才啟用。
• port - sse 模式下 HTTP 伺服器的連接埠。
• debug - 啟用詳細記錄。
• external_hostname - 用於建構 OAuth 權杖對象（audience）的主機名稱。不要加上 HTTP(S) 前綴或連接埠。
• ssl_keyfile - HTTPS 的 SSL 金鑰路徑。（例如 privkey.pem）
• ssl_certfile - HTTPS 的 SSL 憑證路徑。（例如 fullchain.pem）
• registration_psk - 註冊 OAuth 用戶端所需的預先共用金鑰。您需要在瀏覽器中輸入此秘密以核准 OAuth 連線。
• jwt_key_path - 用於 OAuth 權杖的 RSA 金鑰對位置。預設為 .cache/jwt.json。若不存在則自動產生。
• oauth_db_path - OAuth 資料庫檔案的路徑。預設為 .cache/oauth.db。若不存在則自動產生。
• enabled_tools - 要註冊的工具名稱清單。空清單表示啟用所有工具。強烈建議根據使用案例或任務選擇性地啟用工具。請參閱 docs/ 資料夾中的一些範例。
• search_objects - search 工具允許的物件類型。預設為 ["secret"]，但可以包含 user、folder、group 和 role。
• fetch_objects - fetch 工具允許的物件類型。預設為 ["secret"]，但可以包含與 search_objects 相同的值。

執行伺服器

在開發模式下於本機啟動伺服器：

python server.py

啟動時，伺服器會請求一個 bearer 權杖並儲存以供後續 API 請求使用。此專案將擴展以進一步與 Secret Server API 整合。

MCP 工具

伺服器為 Secret Server、Delinea Platform 身分目錄和（可選的）StrongDM 提供 MCP 工具。每個工具都透過 tools/list 發布行為註解（唯讀/破壞性提示）。

ChatGPT / 深度研究相容性

• search(query) - 統一搜尋，返回 {id, title, url} 個結果；物件類型受限於 search_objects 組態鍵（預設：僅限秘密）。
• fetch(id) - 擷取由 search 呈現的單一物件；受限於 fetch_objects。

Secret Server

• run_report(sql_query, report_name=None) - 建立並執行臨時報告。
• ai_generate_and_run_report(description) - 使用 Azure OpenAI 產生 SQL 並執行。需要 Azure OpenAI 變數。
• list_example_reports() - 列出範例查詢和資料表資訊。
• get_secret(id, summary=False) - 擷取秘密或摘要詳細資訊。
• get_folder(id) - 擷取資料夾中繼資料和子項目。
• search_secrets(query, lookup=False) - 搜尋或查詢秘密。
• search_folders(query, lookup=False) - 搜尋或查詢資料夾。
• get_secret_environment_variable(secret_id, environment) - 輸出一個腳本，用於在指定的 shell 中擷取秘密憑證。
• check_secret_template(template_id) - 擷取秘密範本詳細資訊。
• check_secret_template_field(template_id, field_id) - 檢查範本是否包含某個欄位。
• get_secret_template_field(field_id) - 依 ID 擷取特定秘密範本欄位的詳細資訊。
• handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - 核准或拒絕存取請求。
• get_pending_access_requests() - 列出待處理的存取請求。
• get_inbox_messages(read_status_filter=None, take=20, skip=0) - 擷取收件匣訊息。
• mark_inbox_messages_read(message_ids, read=True) - 將訊息標記為已讀或未讀。
• create_secret_with_generated_password(name, secret_template_id, password_field_id, items, folder_id=None, site_id=None, comment=None) - 建立一個密碼由伺服器端產生的秘密；僅返回經過淨化的中繼資料，值永遠不會到達模型。
• update_secret_generated_password(secret_id, field_slug, password_field_id, comment=None) - 在伺服器端輪換秘密的密碼，而不公開該值。
• update_secret_fields(secret_id, field_updates, comment=None, allow_password_fields=False) - 讀取範本 → 修改非密碼欄位 → 驗證流程；除非明確允許，否則拒絕密碼標記欄位。
• set_secret_field_environment_variable(secret_id, field_slug, environment, source="stdin", comment=None) - 輸出一個 shell 腳本（bash/powershell/cmd），在本機讀取值並將其推入秘密欄位，使值完全繞過模型。
• bulk_user_response(user_ids, scenario, comment, confirm=False) - 針對批量使用者操作 API 的意見式事件組合器。情境：compromise、offboard、unlock、reenable、force_logout；需要 confirm=True 加上非空的稽核註解，並在未確認時預覽。
• role_management(action, role_id=None, data=None, params=None) - 管理角色。action 可以是 list、get、create 或 update。列出角色時可使用 params 傳遞選用查詢參數。範例：role_management("update", role_id=3, data={"name": "New Role"})。
• user_role_management(action, user_id, role_ids=None) - 為使用者指派或移除角色。action 是 get、add 或 remove，而 role_ids 是用於新增/移除操作的角色識別碼清單。
• group_management(action, group_id=None, data=None, params=None) - 處理群組。action 可以是 get、list、create 或 delete。執行 get/delete 時提供 group_id，建立群組時提供 data。
• folder_management(action, folder_id=None, data=None, params=None) - 管理資料夾。action 可以是 get、list、create、update 或 delete。執行 get、update 或 delete 時提供 folder_id，建立或更新資料夾時提供 data。
• user_group_management(action, user_id, group_ids=None) - 管理使用者的群組成員資格。action 是 get、add 或 remove。新增或移除成員資格時提供 group_ids 清單。
• group_role_management(action, group_id, role_ids=None) - 控制群組上的角色。使用 list、add 或 remove 操作。新增或移除時提供 role_ids。
• health_check() - 查詢 Secret Server 健康檢查端點並返回目前的服務狀態。

Delinea Platform 使用者和角色

自 v1.0.0 起，標準使用者工具以 Delinea Platform 身分目錄為目標（需要 platform_hostname + PLATFORM_SERVICE_* 憑證；若無則工具返回引導說明而非失敗）：

• user_management(action, user_id=None, data=None, username=None) - Platform 使用者 CRUD。action 接受 get、create、update、delete 或 search。
• search_users(query) - 搜尋 Platform 使用者目錄。
• platform_role_management(action, role_id=None, data=None, page_size=100, query="%") - Platform 角色 CRUD（list、get、create、update、delete）；角色修改由探索驅動，並對 API 範圍不公開角色操作的租用戶返回引導說明。
• platform_user_role_management(action, role_id, user_principals=None) - 在 Platform 角色上執行 list、add 或 remove 使用者操作。
• platform_user_management(...) - user_management 的已棄用別名。

Secret Server 本機使用者（舊版）

適用於未設定 Platform 的僅 SS 部署：

• secretserver_local_user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - v1.0.0 之前的 Secret Server 使用者操作：get、create、update、delete、list_sessions、reset_2fa、reset_password、lock_out。範例：secretserver_local_user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"})。
• search_secretserver_local_users(query) - 搜尋 Secret Server 的本機使用者儲存。

StrongDM 工具（選用，實驗性）

實驗性：StrongDM 後端尚未針對真實 SDM 組織驗證（僅針對 SDK 表面進行單元測試）。預期會有粗糙之處，請回報問題。透過 strongdm 附加元件安裝；完整指南請參閱 docs/strongdm.md。sdm_search、sdm_audit_access、sdm_grant_access（限時的即時或常駐授予）、sdm_revoke_access、sdm_user_management（上線/下線流程）、sdm_role_management、sdm_resource_health、sdm_access_requests、sdm_activity_report、sdm_network_status。破壞性操作需確認並附稽核註解；模糊的名稱相符會返回候選項目而不進行修改。

使用上述伺服器組態變數進行驗證。如果缺少 Azure OpenAI 變數，AI 工具會自動停用。僅註冊 config.json 中列出的工具名稱。空清單會啟用所有工具。

使用案例

文件涵蓋了數個將工具連線到伺服器的工作流程：

• ChatGPT 自訂連接器
• Claude 桌面版
• 遠端 Claude 連接器
• 用於管理的 openwebui
• VSCode Copilot

Docker 快速開始

提供了 Dockerfile，用於執行 MCP 伺服器，無需在本機安裝 Python 相依項。

1. 建置映像檔：

docker build -t dev.local/delinea-mcp:latest .

2. 執行伺服器（透過環境變數傳遞您的憑證）：

docker run --rm -p 8000:8000 \
  -e DELINEA_PASSWORD=<password> \
  -e PLATFORM_SERVICE_PASSWORD=<password> \
  -e DELINEA_DEBUG=1 \
  -e AZURE_OPENAI_KEY=<your-key-or-appropriate-token> \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v mcp-data:/app/data \
  dev.local/delinea-mcp:latest

如上所示，以您的使用者名稱和 URL 填入 config.json。

容器會將 oauth.db 和 jwt.json 儲存在 /app/data。 掛載一個磁碟區（如上方的 mcp-data 所示），讓這些檔案和任何 HTTPS 憑證在執行之間持續存在。

以您的 Secret Server 執行個體的基礎 URL 取代 <https://your-secret-server/SecretServer>，以避免連線錯誤。

伺服器預設會使用 8000 連線至 python server.py 上的連接埠。 在 config.json 中設定 port 選項以覆寫預設值。 啟用 debug: true 以記錄所有傳入的 HTTP 要求。

範例腳本

manual_secret_request.py 腳本示範如何為特定密碼 ID 擷取 OAuth 權杖：

python scripts/manual_secret_request.py <Secret_ID>

執行腳本前，為密碼設定環境變數 SECRET_USERNAME_<id> 和 SECRET_PASSWORD_<id>。 可選用設定 DELINEA_BASE_URL 以覆寫預設的 https://localhost/SecretServer。

執行測試

使用涵蓋率執行單元測試（CI 強制要求至少 70%）：

pip install -r requirements.txt
coverage run -m pytest -q
coverage report --omit "tests/*"

即時測試

部分整合測試需要有效的憑證。 執行測試套件前，設定下列環境變數和可選的 LIVE_SECRET_ID：

export DELINEA_PASSWORD=<password>
# Optional secret used by tests/test_live.py
export LIVE_SECRET_ID=<id>
export SECRET_USERNAME_<id>=<secret_username>
export SECRET_PASSWORD_<id>=<secret_password>

當這些變數存在時，即時測試會執行真實的 API 要求。

生產部署

相依項已固定於 requirements.txt，版本會以語意化版本標記。 從標記的提交建置 Docker 映像檔，並部署至您的生產環境，傳遞必要的環境變數（DELINEA_USERNAME、DELINEA_PASSWORD，可選的 DELINEA_BASE_URL）。 可選功能依賴額外的變數：

• PLATFORM_SERVICE_PASSWORD 與 PLATFORM_HOSTNAME、PLATFORM_SERVICE_ACCOUNT 和 PLATFORM_TENANT_ID 一起啟用使用者管理工具。
• AZURE_OPENAI_KEY 與 AZURE_OPENAI_ENDPOINT 和 AZURE_OPENAI_DEPLOYMENT 一起啟用 AI 報告產生輔助工具。
• SDM_API_ACCESS_KEY 和 SDM_API_SECRET_KEY 啟用實驗性的 StrongDM 工具（需要 strongdm 額外功能；請參閱 docs/strongdm.md）。

使用 OAuth 或 SSE 傳輸時，您可能需要提供 registration_psk，並設定 external_hostname 或 HTTPS 憑證檔案。

儲存庫結構

• delinea_mcp/ - 包含 MCP 工具的套件：tools.py（Secret Server）、user_platform_tools.py（Delinea Platform）、secretserver_users.py（SS 本機使用者）、strongdm_tools.py（StrongDM，可選），以及 transports/（SSE + 可串流 HTTP）和 auth/（內嵌的 OAuth 授權伺服器）。
• server.py - 薄薄的入口點，向 MCP 伺服器註冊所有內容。
• docs/ - 專案文件和產生的 delinea-secret-server-openapi-spec.json。
• scripts/ - 輔助範例，包括 manual_secret_request.py。

安全性考量

內嵌的 OAuth 授權伺服器是為開發、測試和小型部署的便利性；較大型部署應將伺服器部署在其組織的身分提供者前方。目前的安全措施：

• 用戶端註冊（/oauth/register）和授權表單都需要 registration_psk 共用密碼（以常數時間比較）。
• redirect_uri 的值會針對用戶端在授權表單和程式碼重新導向時註冊的 URI 進行驗證。
• 存取權杖是受眾限定的 RS256 JWT；資源探索遵循 RFC 9728（/.well-known/oauth-protected-resource 以及 401/403 回應中的 WWW-Authenticate 標頭）。
• 一律使用 TLS（ssl_keyfile/ssl_certfile 或終止代理）部署——承載權杖和密碼會在每個要求中傳輸。
• 使用 enabled_tools 依使用案例限定工具暴露範圍；密碼 值 刻意不包含在模型內容中（伺服器端密碼產生、環境變數腳本間接方式、密碼欄位保護）。

發行說明

請參閱 CHANGELOG.md 以取得最新功能和路線圖項目的摘要。

路線圖

1. 傳遞式驗證
2. OAuth 用戶端 ID 中繼資料文件（CIMD）用戶端支援（動態用戶端註冊在 MCP 協定修訂版 2026-07-28 中已棄用；受限 PSK 的 /oauth/register 流程仍適用於目前的連接器）
3. 擴充 Delinea Platform 上的工具涵蓋範圍，並新增其他 Delinea 產品

貢獻

歡迎貢獻！ 請針對任何改進開啟問題或發出拉取要求。 所有新程式碼都應包含單元測試，並通過現有的測試套件。

授權

此專案以 MIT 授權 授權。