内容
<div align="center">
# 凭证管理平台
[](LICENSE)
[](https://vaultmcp.dev)
**将 API 密钥排除在 AI IDE 之外**
凭证管理平台是一个加密的秘密凭证库和 MCP 网关。您只需存储一次提供商凭证。您的 AI IDE 连接到一个端点。凭证管理平台仅在调用上游 MCP 服务器时解密秘密凭证 — 您的代理和配置文件永远不会看到原始密钥。
<table>
<tr>
<td align="center">
<img src="https://github.com/user-attachments/assets/f77ed65a-8f28-4f00-8cda-026eec6fa7cd" width="420" />
</td>
<td align="center">
<img src="https://github.com/user-attachments/assets/2c537b03-70e0-493b-8ba4-867601078b5c" width="420" />
</td>
</tr>
</table>
由 **Axiler Labs** 构建 · 产品： **[vaultmcp.dev](https://vaultmcp.dev)**
<img src="docs/assets/clients/claude.svg" alt="Claude Desktop" height="28" />
<img src="docs/assets/clients/vscode.svg" alt="VS Code" height="28" />
<img src="docs/assets/clients/cursor.svg" alt="Cursor" height="28" />
<img src="docs/assets/clients/windsurf.svg" alt="Windsurf" height="28" />
<img src="docs/assets/clients/zed.svg" alt="Zed" height="28" />
<sub>与任何 MCP 客户端配合使用 — Claude Desktop、VS Code、Cursor、Windsurf、Zed 等。</sub>
| **产品** | **自我托管** | **适用于** | **许可证** |
|:-----------:|:-------------:|:-------:|:-----------:|
| [vaultmcp.dev](https://vaultmcp.dev) | `https://YOUR_HOST` | AI IDE + MCP 秘密凭证 | [AGPL-3.0](LICENSE) |
</div>
## 工作原理
<div align="center">
一个凭证库。一个 MCP URL。每个 IDE 都与凭证管理平台通信 — 而不是与您的原始 AWS 或 GitHub 密钥通信。
</div>
1. **登录** 到 [vaultmcp.dev](https://vaultmcp.dev) 并在 vaultmcp.dev 上创建一个工作区。
2. **存储秘密凭证**（静态加密 — 参见 [加密](#加密)）。根据需要与团队成员共享。
3. **将您的 IDE 指向** `https://vaultmcp.dev/mcp`（或您自我托管的 `/mcp`）。
4. **调用工具**，例如 `aws__…` / `github__…`。凭证在服务器端注入 — 永远不会粘贴到 `mcp.json` 中。
```mermaid
flowchart LR
subgraph clients [MCP 客户端]
Claude[Claude]
VSCode[VS Code]
Cursor[Cursor]
Windsurf[Windsurf]
Zed[Zed]
end
subgraph vaultmcp [凭证管理平台]
API[凭证库 · OAuth · MCP 网关]
end
subgraph upstreams [上游]
MCP[AWS · GitHub · 其他 MCP]
end
Claude --> API
VSCode --> API
Cursor --> API
Windsurf --> API
Zed --> API
API -->|注入秘密凭证| MCP
```
## 功能
- **只写凭证库** — 列表 API、MCP 响应和审计日志永远不会返回秘密凭证值
- **服务器端注入** — 仅在调用上游时在 API 中解密
- **私有和共享秘密凭证** — 按用户或工作区范围的可见性
- **GitHub OAuth 或个人令牌** — IDE 的浏览器登录，或 `vmcp_…` 令牌在 `Authorization` 中
- **命名空间工具** — 注册上游一次；以 `provider__tool_name` 调用它们
- **单个公共端口** — Docker Compose 暴露端口 80；API 和 UI 保留在内部网络上
- **可选 CLI** — 将共享工作区秘密凭证注入本地 `npm run dev`（和类似）而无需共享 `.env` 文件
## 快速入门（本地）
**需要：** Node.js 22+，pnpm 9，Docker（Postgres + Redis），以及 [GitHub OAuth 应用](https://github.com/settings/developers)。
```bash
git clone https://github.com/Axiler-Lab/vaultmcp.git
cd vaultmcp
cp .env.example .env
```
至少填写：`VAULT_MASTER_KEY`，`GITHUB_CLIENT_ID`，`GITHUB_CLIENT_SECRET`，`PUBLIC_URL`，`WEB_ORIGIN`，`DATABASE_URL`，`REDIS_URL`。本地默认值在 [`.env.example`](.env.example) 中。
**GitHub OAuth 应用**
| 字段 | 本地（pnpm） | Docker Compose（端口 80） |
| ------------ | -------------------------------------------- | -------------------------------------------- |
| 首页网址 | `http://localhost:5173` | `http://YOUR_SERVER_IP` |
| 回调网址 | `http://localhost:3001/auth/github/callback` | `http://YOUR_SERVER_IP/auth/github/callback` |
回调网址必须与 `PUBLIC_URL` 匹配。
```bash
docker compose up -d postgres redis
pnpm install
pnpm --filter @vaultmcp/shared build
pnpm db:generate # 首次 / 架构更改后
pnpm db:migrate
pnpm dev:api # :3001
pnpm dev:web # :5173
```
打开 [http://localhost:5173](http://localhost:5173) → 登录 → 创建工作区 → 添加秘密凭证 → 注册上游（[AWS 示例](examples/aws-upstream.md)）。主机运行的 AWS `uvx` 上游需要 [`uv`](https://docs.astral.sh/uv/) 在您的 `PATH` 中。
## Docker Compose
**端口 80** 上有一个公共入口点。API 和 Web 不直接发布。
```bash
cp .env.example .env
# 设置 PUBLIC_URL、WEB_ORIGIN、GITHUB_*、VAULT_MASTER_KEY
# VITE_API_URL= # 空 = 同源
# COOKIE_SECURE=false # HTTPS 后面为 true
docker compose up --build
```
| 界面 | 网址 |
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| Web UI | [http://localhost/](http://localhost/) |
| 健康检查 | [http://localhost/health](http://localhost/health) |
| MCP | [http://localhost/mcp](http://localhost/mcp) |
| OAuth 发现 | [http://localhost/.well-known/oauth-protected-resource](http://localhost/.well-known/oauth-protected-resource) |
迁移在 API 容器启动时运行。生产环境说明：[docs/DEPLOY.md](docs/DEPLOY.md)。
## 连接 Cursor（或任何 MCP 客户端）
**Cursor**、**Claude Desktop**、**VS Code**、**Windsurf**、**Zed** 等 MCP 客户端使用相同的配置形状。使用 OAuth（浏览器登录）或来自 **Connect** 标签的个人访问令牌。永远不要在客户端配置中放置提供商秘密凭证。
**OAuth**（托管）
```json
{
"mcpServers": {
"vaultmcp": {
"url": "https://vaultmcp.dev/mcp"
}
}
}
```
**个人令牌**（`vmcp_…` 来自 Connect）
```json
{
"mcpServers": {
"vaultmcp": {
"url": "https://vaultmcp.dev/mcp",
"headers": {
"Authorization": "Bearer vmcp_…"
}
}
}
}
```
自我托管：替换为 `https://YOUR_HOST/mcp`。本地 API：`http://localhost:3001/mcp`。
Cursor：`~/.cursor/mcp.json` 或 `.cursor/mcp.json`。其他客户端使用它们自己的 MCP 配置路径。
身份验证后：`list_workspaces` → `use_workspace` → 调用命名空间工具（`github__…`，`aws__…`）。
## 本地环境 CLI（可选）
对于本地应用程序（非 MCP 代理）中的共享团队秘密凭证，请使用 [`@vaultmcp-axiler/cli`](https://www.npmjs.com/package/@vaultmcp-axiler/cli)：
```bash
npx @vaultmcp-axiler/cli@latest login --token vmcp_… --url https://YOUR_HOST
npx @vaultmcp-axiler/cli@latest run -w your-slug -- npm run dev
```
使用 **Runtime env（CLI）** 预设创建 PAT（仅 `env` 作用域）。MCP 令牌和环境令牌不可互换。优先使用 `run` 而不是 `env`，以便秘密凭证保留在子进程中。
完整指南： **[docs/CLI.md](docs/CLI.md)**。
## 加密
秘密凭证 **值** 使用 **AES-256-GCM** 在静止时加密：
- 每个工作区都有自己的数据加密密钥（DEK）
- DEKs 由 `VAULT_MASTER_KEY` 封装（保留在数据库之外）
- GCM AAD 将密文绑定到 `workspaceId`，因此 blob 不能在工作区之间交换
- 解密仅在服务器端发生 — 用于 MCP 上游注入，或选择加入 CLI 导出
- 秘密凭证 **名称** 和其他元数据 **未** 加密（因此 UI 可以在不解密的情况下列出和授权）
将 `VAULT_MASTER_KEY` 视为根凭证。旋转提供商秘密凭证，而无需更改 IDE 配置。
此外：列表 API 和审计日志永远不会返回明文值；查看者无法调用秘密凭证支持的工具或导出运行时环境。
详情： **[docs/CRYPTO.md](docs/CRYPTO.md)**。
## 仓库布局
```
apps/api 网关，OAuth，REST，上游代理
apps/web 控制平面 UI
packages/shared 加密帮助程序 + 共享模式
packages/cli 本地环境注入 CLI
deploy/ 反向代理配置
docs/ 部署，CLI 和加密指南
examples/ 上游演练
```
## 为什么是 AGPL
凭证管理平台通常作为网络服务运行。 **AGPL-3.0-only** 意味着如果您修改它并通过网络提供该服务，您必须共享相应的源代码。这样可以让托管的分支保持诚实，同时仍然允许自我托管和贡献。
## 贡献
凭证管理平台是来自 **Axiler Labs** 的开源项目。我们欢迎社区的帮助 — 问题和拉取请求非常受欢迎，尤其是围绕安全性、可靠性、文档和 MCP 兼容性。
贡献方式：
- [打开问题](https://github.com/Axiler-Lab/vaultmcp/issues) 以报告错误或清晰的功能想法
- [发送拉取请求](https://github.com/Axiler-Lab/vaultmcp/pulls)（小而集中的更改最容易审查）
- 改进常见上游的文档和示例
通过贡献，您同意您的工作根据 **AGPL-3.0-only** 许可，与存储库的其他部分相同。永远不要提交秘密凭证；仅使用 `.env.example` 进行变量命名。
在 **[vaultmcp.dev](https://vaultmcp.dev)** 上了解更多 · Axiler Labs： **[axiler.com](https://axiler.com)**。
## 许可证
版权所有 © 2026 **Axiler Labs**。
凭证管理平台根据 [GNU Affero General Public License v3.0 only](LICENSE)（`AGPL-3.0-only`）许可。
