内容
# Vultr MCP
一款适用于 [Vultr](https://www.vultr.com/) 云平台的 **Python MCP（模型上下文协议）服务器**，基于 [FastMCP](https://gofastmcp.com) 构建。
工具直接从 Vultr OpenAPI 规范生成，因此 AI 代理（Claude、Cursor、VS Code Copilot 等）可以通过自然语言配置和管理 Vultr 基础设施。支持 **本地（STDIO）** 和 **远程（HTTP）** 传输，每个请求进行身份验证，工具排除，以及高效的类别端点。
> **v2** 是从头开始使用 Python/FastMCP 重写的。原始 PHP 服务器存在于此存储库的 git 历史记录中。
## 要求
- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
---
## 快速入门
### 本地（STDIO）
```bash
uv sync
VULTR_API_KEY=您的_VULTR_API_KEY uv run python -m vultr_mcp
```
服务器在由 MCP 客户端启动时自动检测 STDIO。在 STDIO 模式下，凭证来自 `VULTR_API_KEY`。
### 远程（HTTP）
```bash
VULTR_MCP_TRANSPORT=http uv run python -m vultr_mcp
```
在端口 8080（可通过 `SERVER_PORT` 配置）上提供可流式传输的 HTTP，以及 `/healthz`。每个用户在每个请求中提供自己的 Vultr API 密钥（参见身份验证）。
---
## 工具表面
工具从 `openapi.json` 通过 `FastMCP.from_openapi()` 生成 - 没有手写的工具代码。
### 排除类别
身份验证和凭证管理类别 **默认排除**，以便它们不被代理访问（与 GitHub/Stripe/DigitalOcean MCP 的策略相同）：`api-keys`、`users`、`iam`、`scim`、`organizations`、`oidc`。这些权限的执行应在附加到 OAuth 客户端应用程序的 IAM 策略中；排除工具是 UX 层的卫生措施。
通过 `VULTR_MCP_EXCLUDED_CATEGORIES`（逗号分隔的标签；空字符串保留所有内容 - 适用于本地 STDIO 使用）覆盖。
### 类别端点（高效令牌）
**根端点通过单个连接提供所有（非排除）工具** - 当您的客户端仅允许您添加一个或两个 MCP 服务器时最佳，因此您希望在一个插槽中拥有所有内容。每个类别还获得 **其自己的端点，仅暴露该类别的工具** - 当您有空间添加多个聚焦连接并希望每个连接范围限定：
```
https://vultrmcp.com/ # 所有工具
https://vultrmcp.com/instances # 仅 VPS 实例工具
https://vultrmcp.com/kubernetes # 仅 VKE 工具
https://vultrmcp.com/dns # 仅 DNS 工具
https://vultrmcp.com/container-registry # 多个单词标签被转换为 slug
```
路径为小写，短线分隔，**裸路径 - 不需要尾部斜线**。常见类别：`instances`、`baremetal`、`kubernetes`、`dns`、`firewall`、`block`、`snapshot`、`ssh`、`iso`、`reserved-ip`、`load-balancer`、`managed-databases`、`container-registry`、`vpcs`、`s3`、`cdns`、`billing`、`account`、`plans`、`region`、`os`。
向您的客户端添加多个类别服务器，以涵盖您使用的内容，而无需加载所有内容。通过 `VULTR_MCP_CATEGORY_ENDPOINTS`（逗号分隔的 slug；默认为所有非排除项）配置要安装的端点。
---
## 身份验证
### 头部 / API 密钥（当前有效）
每个请求都包含用户的 Vultr API 密钥，该密钥转发到 `api.vultr.com`:
```
Authorization: Bearer 您的_VULTR_API_KEY
```
当没有活动 OAuth 层时，也接受 `X-Vultr-API-Key: 您的_VULTR_API_KEY`。
### OAuth 2.1 / OIDC（零配置）
设置 `VULTR_OIDC_ENABLED=true`（加上 OAuth 应用程序凭证）以使用 FastMCP 的 `OAuthProxy` 在 Vultr 的 OIDC 提供程序前面。这为 MCP 客户端提供了粘贴 URL 的体验 - 动态客户端注册，用户无需输入客户端 ID/密钥 - 而服务器持有批准的客户端凭证。`DualTokenVerifier` 同时接受 **OIDC JWT 和原始 API 密钥**，因此头部路径在启用 OAuth 时继续有效。
参见 `k8s/configmap.yaml` 和 `src/vultr_mcp/auth.py` 以获取所需变量。
### 客户端配置示例（Claude Desktop，远程）
Claude Desktop 的配置通过 `mcp-remote` 桥支持远程服务器：
```json
{
"mcpServers": {
"vultr": {
"command": "cmd",
"args": ["/c", "npx", "-y", "mcp-remote",
"https://vultrmcp.com/instances",
"--header", "Authorization: Bearer 您的_VULTR_API_KEY"]
}
}
}
```
（在非 Windows 系统上，删除 `"/c"` 并使用 `"npx"` 作为命令。）
---
## 配置（环境）
| 变量 | 用途 |
|---|---|
| `VULTR_MCP_TRANSPORT` | `stdio`（默认）或 `http` |
| `VULTR_API_KEY` | STDIO/本地模式下的凭证 |
| `VULTR_API_BASE_URL` | 默认 `https://api.vultr.com/v2` |
| `SERVER_HOST` / `SERVER_PORT` | HTTP 绑定（默认 `0.0.0.0:8080`）|
| `SSL_VERIFY` | 验证上游 TLS（默认 `true`）|
| `VULTR_MCP_EXCLUDED_CATEGORIES` | 要删除的标签（默认身份验证集；空字符串禁用）|
| `VULTR_MCP_CATEGORY_ENDPOINTS` | 要安装的类别端点（默认：所有非排除项）|
| `MCP_RESOURCE_URL` | 公共 URL，用于 OAuth + 主机允许列表 |
| `MCP_ALLOWED_HOSTS` | 额外的 DNS 反绑定保护主机 |
| `VULTR_OIDC_ENABLED` | 启用 OAuthProxy（默认 `false`）|
| `VULTR_OIDC_PROVIDER_ID` / `VULTR_OAUTH_CLIENT_ID` / `VULTR_OAUTH_CLIENT_SECRET` | 批准的 OAuth 应用程序凭证 |
| `REDIS_HOST` / `REDIS_PORT` | 用于 OAuth DCR 状态的 Redis（适用于多副本 OAuth）|
---
## 部署
### Docker
```bash
docker build -t vultr-mcp-py:latest .
docker run --rm -p 8080:8080 -e VULTR_MCP_TRANSPORT=http vultr-mcp-py:latest
```
镜像在 uvicorn 下以非 root 用户身份运行 `python -m vultr_mcp`。
### Kubernetes
清单位于 `k8s/`（部署、服务、configmap、`secret.yaml.example`、redis）。复制 `secret.yaml.example` 到 `secret.yaml`（gitignored），填写值，然后应用：
```bash
cp k8s/secret.yaml.example k8s/secret.yaml # 然后编辑
kubectl apply -f k8s/
```
在轮询 ingress 后运行 2 个副本；服务器使用 **无状态 HTTP**，因此不需要会话亲和力。OAuth DCR 状态通过 Redis 共享。
---
## 开发
```bash
uv sync
uv run pytest # 测试套件
uv run python -m vultr_mcp # 本地运行（STDIO）
```
工具在启动时自动从 `openapi.json` 重新生成 - 要更新工具表面，请用最新的 Vultr 规范替换 `openapi.json`。
