内容
# OCI 密钥 MCP
OCI Vault 文档中规定的公共密钥控制平面和数据平面 API 的 MCP 服务器。
## 安装
```sh
git clone https://github.com/kevinwengh/oci-secrets-mcp.git
cd oci-secrets-mcp
uv sync
```
## OCI 身份验证
服务器使用 OCI Python SDK 签署 outbound 请求。服务器从不接受私钥、Bearer Token 或来自 MCP 工具的授权头。
| 模式 | 所需配置 |
| --- | --- |
| `api_key`（默认） | `~/.oci/config`，可选 `OCI_CONFIG_FILE` 和 `OCI_CONFIG_PROFILE` |
| `security_token` | 配置了安全令牌的 OCI 配置文件 |
| `instance_principal` | `OCI_REGION` 和 OCI 计算实例主体 |
| `instance_principal_delegation_token` | `OCI_REGION` 和 `OCI_DELEGATION_TOKEN_FILE` |
| `resource_principal` | `OCI_REGION` 和支持的 OCI 资源主体环境 |
| `resource_principal_delegation_token` | `OCI_REGION`，资源主体和 `OCI_DELEGATION_TOKEN_FILE` |
| `oke_workload_identity` | `OCI_REGION` 和 OKE 工作负载身份环境 |
使用 `OCI_SECRETS_MCP_AUTH_MODE` 选择非默认提供程序。
对于安全令牌和委托令牌模式，请使用正常的 OCI 工具刷新令牌文件。如果 OCI 返回 `401 NotAuthenticated`，服务器将从当前凭证源重建两个 SDK 客户端，并重试请求一次。
### API 密钥示例
OCI 用户身份验证令牌用于容器注册表或 SMTP 等服务，不能签署 OCI SDK 请求。请改用 API 签名密钥对：将公钥上传到 OCI 用户，并将匹配的私钥保存在此存储库之外。
将私钥保存为用户权限，仅限用户读取，例如：
```text
/absolute/path/to/.oci/oci-secrets-mcp-api-key.pem
```
不要将私钥粘贴到此 README 或 MCP 客户端配置中。在 OCI 配置文件中添加类似以下内容的配置文件，替换每个占位符为自己的值：
```ini
[OCI_SECRETS_MCP]
user=<USER_OCID>
fingerprint=<KEY_FINGERPRINT>
tenancy=<TENANCY_OCID>
region=<OCI_REGION>
key_file=/absolute/path/to/.oci/oci-secrets-mcp-api-key.pem
```
配置 MCP 客户端以选择该配置文件。配置格式特定于客户端。
### Claude Desktop
Claude Desktop 使用 JSON。在其 MCP 配置中添加以下服务器条目：
```json
{
"mcpServers": {
"oci-secrets": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/oci-secrets-mcp",
"run",
"oci-secrets-mcp"
],
"env": {
"OCI_SECRETS_MCP_AUTH_MODE": "api_key",
"OCI_CONFIG_FILE": "/absolute/path/to/.oci/config",
"OCI_CONFIG_PROFILE": "OCI_SECRETS_MCP"
}
}
}
}
```
更改 Claude Desktop 配置后，请重新启动它。
### Codex
Codex 使用 TOML。在 `~/.codex/config.toml` 或受信任项目中的 `.codex/config.toml` 中添加以下内容：
```toml
[mcp_servers.oci-secrets]
command = "uv"
args = [
"--directory",
"/absolute/path/to/oci-secrets-mcp",
"run",
"oci-secrets-mcp",
]
[mcp_servers.oci-secrets.env]
OCI_SECRETS_MCP_AUTH_MODE = "api_key"
OCI_CONFIG_FILE = "/absolute/path/to/.oci/config"
OCI_CONFIG_PROFILE = "OCI_SECRETS_MCP"
```
更改 Codex 配置后，请重新启动它，然后验证服务器是否已注册：
```sh
codex mcp list
```
上述环境变量属于 MCP 客户端配置。它们在 Claude Desktop 或 Codex 启动服务器时应用。如果直接在 shell 中运行 `uv run oci-secrets-mcp`，请先导出相同的变量；否则，服务器将使用其默认值，包括 `DEFAULT` OCI 配置文件。
租户 OCID 也可以用作根分区 ID。例如，使用以下方式调用 `list_secrets`：
```json
{
"compartment_id": "<TENANCY_OR_COMPARTMENT_OCID>",
"vault_id": "<VAULT_OCID>"
}
```
## 运行
标准输入输出是默认传输，适用于本地 MCP 客户端：
```sh
uv run oci-secrets-mcp
```
可选的流式 HTTP 传输仅限于环回：
```sh
uv run oci-secrets-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```
> [!WARNING]
> 流式 HTTP 传输不验证调用者或验证浏览器来源。环回绑定减少了网络暴露，但不能保护免受不受信任的本地进程或 DNS 重新绑定场景的影响。任何到达端点的调用者都可以使用服务器配置的 OCI 身份检索机密内容，并可以使用 `confirm=true` 提交更改状态的调用。除非您单独隔离并保护了 HTTP 端点，否则请优先使用标准输入输出。
服务器不允许非环回绑定，包括网关绑定。请参阅上面的单独 Claude Desktop 和 Codex 配置示例，了解标准输入输出客户端设置。
## 安全性和 IAM
所有更改状态的工具都有 MCP 破坏性注解，需要 `confirm=true`；这包括创建、更新、轮换、分区移动和删除/轮换调度或取消。机密包检索返回机密内容，因此仅授予执行 OCI 主体所需的 Vault 权限，并将 MCP 响应视为敏感信息。
`confirm=true` 检查是防止意外更改的防护措施，而不是身份验证或授权边界。OCI IAM 和 MCP 客户端访问策略仍然是安全边界。
创建和更新请求使用 snake_case 字段名称的 typed MCP 架构，并在传输前转换为 OCI SDK 模型。成功的结果包含：
- `data`：OCI SDK 响应模型转换为 JSON。
- `opc_request_id`：OCI 请求标识符。
- `headers`：允许列出的分页、ETag、工作请求、位置和重试元数据（如果存在）。
- `status`：HTTP 响应状态。
## 验证
```sh
uv run ruff check .
uv run pytest
```
## 许可证
在 [MIT License](LICENSE) 下许可。
