← 返回作品集

cred-mcp

AI Agent 的憑證管理層——搭橋 Vaultwarden 與 AI agent，搜尋、複製、密封注入，明文永遠不進 LLM context。

Go MCP Vaultwarden OS Keychain HPKE Open Source

GitHub Repository Releases (v0.4.5) ✕ pty-mcp 整合相關：pty-mcp

核心問題

AI agent 要完成工作就需要密碼——SSH 登入、sudo、API key、資料庫連線。但如果密碼出現在對話裡，就進了 LLM context，可能進 log、進快取、進訓練資料。

cred-mcp 解決這個問題：AI 呼叫工具取得憑證，但每個工具的回傳都只有 metadata，密碼本體透過 clipboard 或 HPKE 密封通道傳遞，不出現在任何 response body 或 log 裡。

AI Agent（Claude Code）

│

│ MCP tools（只傳 metadata）

▼

cred-mcp MCP server

┌────┴────────────────────┐

│ │ │

▼ ▼ ▼

OS Keychain Vaultwarden HPKE Seal

（stash 操作）（vault 操作）（→ pty-mcp）

│ │ │

clipboard clipboard WriteRaw PTY

（TTL auto-clear）（TTL auto-clear）（zeroize）

✗ LLM 看不到 ✗ LLM 看不到 ✗ LLM 看不到

三層憑證存取

Layer 1 Stash — OS keychain 快速存取

把密碼存在 OS keychain（macOS Keychain / Windows Credential Manager / Linux Secret Service），AI 用名稱取用，值走 clipboard 不走 response。

save_stash — 從 clipboard 存入

AI 呼叫 save_stash(name)，cred-mcp 讀取當前 clipboard 寫入 keychain。值從不出現在對話裡——操作者自己 copy，AI 負責存。

copy_stash — 放回 clipboard

AI 呼叫 copy_stash(name)，cred-mcp 從 keychain 讀取，放上 clipboard，TTL 到期後自動還原。AI 只收到 {"status": "ok", "ttl_seconds": 30}。

# 存一個 API key（操作者先 copy 到 clipboard）

save_stash(name: "prod-api-key") → {"status": "saved"}

# 取用（放到 clipboard 30 秒，到期自動清除）

copy_stash(name: "prod-api-key") → {"status": "ok", "ttl_seconds": 30}

→ AI 永遠看不到 API key 本體

Layer 2 Vault — Vaultwarden 整合

直接存取自托管的 Vaultwarden vault。搜尋時回傳 metadata，複製時把密碼放上 clipboard，AI 只看到項目名稱和狀態。

vault_search — 搜尋項目

依名稱、username、URI 搜尋，回傳 ID 和 metadata，不含密碼。AI 用 ID 做後續操作。

vault_copy — 複製到 clipboard

指定項目 ID，cred-mcp 取出密碼放上 clipboard（帶 TTL）。AI 收到的 response 不含密碼本體。

vault_add / vault_update

新增或更新 vault 項目。密碼來源 "dialog"（彈出原生對話框）或 "clipboard"，不接受直接傳值。

Session 自動續期（v0.3.2）

Vaultwarden session 閒置 30 分鐘或 8 小時絕對逾期後，下次 vault 操作自動重新驗證，不需要手動重連。

# 搜尋 vault 找到 SSH 憑證

vault_search(query: "prod server") → [{id: "abc-123", name: "prod-server-ssh", username: "admin"}]

# 複製密碼到 clipboard（TTL 30 秒）

vault_copy(id: "abc-123") → {"status": "ok", "name": "prod-server-ssh", "ttl_seconds": 30}

→ 操作者貼到 SSH prompt；AI 從未看到密碼

Layer 3 HPKE PAM 協議 — 全自動密封注入（v0.4.0）

前兩層需要操作者手動貼上密碼。HPKE 協議讓 AI 完全自動完成需要密碼的操作，同時明文仍然不進 LLM context。整合 pty-mcp 實現端對端密封傳遞。

流程：pty-mcp 生成公鑰 bundle → AI 傳給 cred-mcp 取得授權 → cred-mcp 以消費者公鑰封裝密碼 → AI 傳回 pty-mcp 解密注入 PTY。AI 全程只傳遞公鑰和密文，從未接觸明文。

request_authorization — ACL 檢查 + 發授權 token

檢查消費者（pty-mcp）是否被允許請求指定項目，通過後發出單次使用的授權 token，綁定 (item, consumer, purpose)。

vault_seal — HPKE 封裝

驗證 ConsumerBundle identity key、消耗授權 token、從 vault 取出明文、用消費者的 X25519 session key HPKE 封裝，回傳 SealedBox。明文不離開 cred-mcp 程序。

# 全自動 SSH 密碼注入（AI 全程不見明文）

bundle = pty-mcp.get_credential_bundle(session_id) → 公鑰 bundle

token = request_authorization(item_id, bundle) → 單次授權 token

sealed = vault_seal(item_id, bundle, token) → HPKE SealedBox

pty-mcp.inject_secret(session_id, sealed) → 解密 → 寫入 PTY

→ {"success": true}，SSH 登入完成，AI 從未看過密碼

Consumer Registry 設定

使用 HPKE 協議前需要建立 registry，告訴 cred-mcp 哪些消費者可以請求哪些 vault 項目：

# ~/.config/cred-mcp/registry.yaml

consumers:

pty-mcp:

identity_pub_key: "b519ada7..." # hex，從 get_credential_bundle 取得

allowed_items:

- "*" # 或指定特定 vault item UUID

allowed_purposes:

- "ssh-login"

approval_mode: auto # auto 或 required（Touch ID）

版本演進

v0.4.4–v0.4.5：Vaultwarden 改為可選

v0.4.4 讓 Vaultwarden 成為可選元件：不設定 CRED_MCP_VAULT_URL 的情況下，cred-mcp 依然可以正常啟動並使用 OS keychain stash 和 HPKE 協議，只是 vault_* 工具會回傳「vault 未設定」的提示。這讓不需要 vault 的場景（純 stash 或純 HPKE）可以零設定上手。同版新增 CRED_MCP_UNLOCK env var，可設定 vault 解鎖政策。v0.4.5 為 hotfix：修正 vaultConfigured 未從 OS keychain stash 讀取 vaultwarden-url 的問題（透過 save_stash 存入的 vault URL 在 v0.4.4 下誤判為未設定）。

v0.4.0：HPKE AI-native PAM 協議

v0.4.0 是架構性升級：新增 request_authorization 和 vault_seal 兩個工具，實作完整的 HPKE 密封傳遞協議。配合 pty-mcp v0.11.0 的 get_credential_bundle 和 inject_secret，形成完整的端對端憑證傳遞鏈。

v0.3.x：Vaultwarden 整合 + 穩定性

v0.3.0 重寫所有工具描述（以 AI 可用性為準），新增 username 搜尋，統一環境變數命名。v0.3.2 修正 vault session 逾期後需要手動重連的問題——現在自動重新驗證，不中斷工作流。

v0.2.0：Vault + Stash 雙層架構

加入 Vaultwarden API 整合，完整的 vault_search / vault_copy / vault_add / vault_update；以及 OS keychain stash 層（save_stash、copy_stash、list_stash、delete_stash）。確立「密碼走 clipboard，AI 看 metadata」的核心設計。

MCP Tools 一覽

工具	說明
ping	健康檢查，回傳版本和時間；永遠繞過 session gate
save_stash	讀取 clipboard，以 `name` 存入 OS keychain；clipboard 不清除
copy_stash	從 OS keychain 取出，放上 clipboard（帶 TTL）；到期自動還原；只回傳 metadata
list_stash	列出所有已存名稱和 metadata，不回傳值；可用於確認哪些密碼已遷移
delete_stash	從 OS keychain 刪除指定項目
vault_search	搜尋 Vaultwarden（名稱、username、URI），回傳 metadata，不含密碼
vault_copy	指定 item ID，把密碼放上 clipboard（帶 TTL）；只回傳 metadata
vault_add	新增 vault 項目；密碼來源 `"dialog"`（原生對話框）或 `"clipboard"`
vault_update	更新 vault 項目欄位；密碼更新同 vault_add
request_authorization	檢查 registry ACL，發出單次授權 token（綁定 item / consumer / purpose）（v0.4.0）
vault_seal	驗證 ConsumerBundle、消耗授權 token、HPKE 封裝 vault 密碼，回傳 SealedBox（v0.4.0）

所有涉及密碼的工具回傳都只包含 metadata（name、status、ttl_seconds 等）。密碼本體不序列化進任何 response 或 stderr log。

安裝

# 方法一：Claude Code plugin（推薦）

claude plugin install cred-mcp@claude-plugins-official

# 方法二：手動安裝 binary

curl -fsSL https://raw.githubusercontent.com/raychao-oao/cred-mcp/main/install.sh | sh

# 方法三：從 source

go install github.com/raychao-oao/cred-mcp@latest

# 設定 Vaultwarden（可選；不設定也可正常啟動，vault_* 工具停用）

CRED_MCP_VAULT_URL=https://vault.example.com

CRED_MCP_VAULT_EMAIL=you@example.com

技術選擇

Go — 跨平台單一 binary，macOS / Linux / Windows 全支援，OS keychain 用 go-keyring
HPKE（DHKEM-X25519 + HKDF-SHA256 + ChaCha20Poly1305） — Go stdlib crypto/hpke，密碼學正確，不自造加密
單次使用 auth token — 授權 token 有 TTL 且只能用一次，綁定 (item, consumer, purpose)，防重放
消費者 registry ACL — YAML 設定哪些 consumer 可以請求哪些 vault 項目，glob pattern 匹配，auto / required（Touch ID）兩種核准模式
Clipboard TTL — 密碼放上 clipboard 後自動倒數，到期還原先前內容，人工貼上後不受影響

為什麼要獨立的 MCP server？

讓 AI 直接讀取 .env、config file、或請操作者把密碼打在 chat 裡，是現在最常見的作法——但這些都讓明文進了 LLM context。

cred-mcp 把「AI 知道去哪找密碼」和「AI 看到密碼本體」這兩件事分開。AI 可以完整執行需要憑證的工作流，但 session log、conversation history、或任何 AI response 裡都不會出現密碼。這對長期運作的 agent、需要審計的環境、或有合規要求的場景都重要。