内容
# Terraform 注册表 MCP 服务器
一个模型上下文协议（MCP）服务器，提供与 Terraform 注册表 API 交互的工具。此服务器使 AI 代理能够查询提供者信息、资源详细信息和模块元数据。
> [!IMPORTANT]
> 该项目曾用作新官方 [Terraform MCP 服务器](https://github.com/hashicorp/terraform-mcp-server) 的概念验证（PoC）。由于该项目已被存档，因此不再使用该项目。
## 安装
### 在 Cursor 中安装
要在 [Cursor](https://cursor.sh/) 中安装和使用此 MCP 服务器：
1. 在 Cursor 中，打开设置（⌘+,）并导航到“MCP”选项卡。
2. 点击“+ 添加新的 MCP 服务器”。
3. 输入以下内容：
- 名称：terraform-registry
- 类型：command
- 命令：npx -y terraform-mcp-server
4. 点击“添加”，然后滚动到服务器并点击“禁用”以启用服务器。
5. 如果需要，重启 Cursor 以确保 MCP 服务器正确加载。
### 在 Claude Desktop 中安装
要在 Claude Desktop 中安装和使用此 MCP 服务器：
1. 在 Claude Desktop 中，打开设置（⌘+,）并导航到“开发者”选项卡。
2. 点击窗口底部的“编辑配置”。
3. 编辑文件（~/Library/Application Support/Claude/claude_desktop_config.json）以添加以下代码，然后保存文件。
```json
{
"mcpServers": {
"terraform-registry": {
"command": "npx",
"args": ["-y", "terraform-mcp-server"]
}
}
}
```
4. 重启 Claude Desktop 以确保 MCP 服务器正确加载。
## 工具
此 MCP 服务器提供以下工具：
### 核心注册表工具
| 工具 | 描述 |
|------|-------------|
| `providerDetails` | 获取有关 Terraform 提供者的详细信息 |
| `resourceUsage` | 获取 Terraform 资源的示例用法和相关资源 |
| `moduleSearch` | 根据查询搜索和推荐 Terraform 模块 |
| `listDataSources` | 列出提供者的所有可用数据源及其基本详细信息 |
| `resourceArgumentDetails` | 获取资源类型参数的综合详细信息 |
| `moduleDetails` | 检索 Terraform 模块的详细元数据 |
| `functionDetails` | 获取有关 Terraform 提供者函数的详细信息 |
| `providerGuides` | 列出和查看提供者特定的指南和文档 |
| `policySearch` | 在 Terraform 注册表中搜索策略库 |
| `policyDetails` | 获取有关特定策略库的详细信息 |
### Terraform Cloud 工具
这些工具需要 Terraform Cloud API 令牌（`TFC_TOKEN`）：
| 工具 | 描述 |
|------|-------------|
| `listOrganizations` | 列出经过身份验证的用户可以访问的所有组织 |
| `privateModuleSearch` | 在组织中搜索私有模块 |
| `privateModuleDetails` | 获取私有模块的详细信息 |
| `explorerQuery` | 查询 Terraform Cloud Explorer API 以分析数据 |
| `listWorkspaces` | 列出组织中的工作区 |
| `workspaceDetails` | 获取特定工作区的详细信息 |
| `lockWorkspace` | 锁定工作区以防止运行 |
| `unlockWorkspace` | 解锁工作区以允许运行 |
| `listRuns` | 列出工作区的运行 |
| `runDetails` | 获取特定运行的详细信息 |
| `createRun` | 为工作区创建新的运行 |
| `applyRun` | 应用已规划的运行 |
| `cancelRun` | 取消正在进行的运行 |
| `listWorkspaceResources` | 列出工作区的资源 |
## 资源
MCP 服务器支持以下资源 URI 以通过 `resources/*` 方法进行列表和读取：
| 资源类型 | 示例 URI(s) | 描述 |
|---------------|----------------|-------------|
| **提供者** | `terraform:providers` | 列出所有命名空间/提供者 |
| | `terraform:provider:<namespace>/<name>` | 获取特定提供者的详细信息 |
| **提供者版本** | `terraform:provider:<namespace>/<name>/versions` | 列出提供者的可用版本 |
| **提供者资源** | `terraform:provider:<namespace>/<name>/resources` | 列出提供者的资源 |
| | `terraform:resource:<namespace>/<name>/<resource_name>` | 获取特定资源类型的详细信息 |
| **提供者数据源** | `terraform:provider:<namespace>/<name>/dataSources` | 列出提供者的数据源 |
| | `terraform:dataSource:<namespace>/<name>/<data_source_name>` | 获取特定数据源的详细信息 |
| **提供者函数** | `terraform:provider:<namespace>/<name>/functions` | 列出提供者的函数 |
| | `terraform:function:<namespace>/<name>/<function_name>` | 获取特定函数的详细信息 |
服务器还支持 `resources/templates/list` 以提供创建以下内容的模板：
- `terraform:provider`
- `terraform:resource`
- `terraform:dataSource`
## 提示
提供了以下提示以生成上下文响应：
| 提示 | 描述 | 必需参数 |
|--------|-------------|-------------------|
| `migrate-clouds` | 生成 Terraform 代码以在云提供者之间迁移基础设施 | `sourceCloud`, `targetCloud`, `terraformCode` |
| `generate-resource-skeleton` | 帮助用户使用最佳实践快速构建新的 Terraform 资源 | `resourceType` |
| `optimize-terraform-module` | 为改进 Terraform 代码提供可行的建议 | `terraformCode` |
| `migrate-provider-version` | 协助提供者版本升级和重大更改 | `providerName`, `currentVersion`, `targetVersion`, `terraformCode`（可选） |
| `analyze-workspace-runs` | 分析最近的运行失败并为 Terraform Cloud 工作区提供故障排除指南 | `workspaceId`, `runsToAnalyze`（可选，默认值：5） |
### 提示的已知问题
**注意**：`getPrompt` 功能存在已知问题，可能会导致服务器崩溃。服务器正确注册提示并可以列出它们，但使用 `getPrompt` 方法的直接请求可能会导致连接问题。正在调查中，可能与 SDK 兼容性或实现细节有关。在解决问题之前，请使用 `listPrompts` 查看可用提示，但避免直接调用 `getPrompt`。
## 运行服务器
服务器使用 stdio 传输协议进行 MCP 通信：
```bash
npm install
npm start
```
### 使用环境变量配置
服务器可以使用环境变量进行配置：
| 环境变量 | 描述 | 默认值 |
|---------------------|-------------|---------------|
| `TERRAFORM_REGISTRY_URL` | Terraform 注册表 API 的基本 URL | https://registry.terraform.io |
| `DEFAULT_PROVIDER_NAMESPACE` | 提供者的默认命名空间 | hashicorp |
| `LOG_LEVEL` | 日志级别（error, warn, info, debug） | info |
| `REQUEST_TIMEOUT_MS` | API 请求超时（毫秒） | 10000 |
| `RATE_LIMIT_ENABLED` | 启用 API 请求的速率限制 | false |
| `RATE_LIMIT_REQUESTS` | 时间窗口内允许的请求数 | 60 |
| `RATE_LIMIT_WINDOW_MS` | 速率限制的时间窗口（毫秒） | 60000 |
| `TFC_TOKEN` | 用于私有注册表访问的 Terraform Cloud API 令牌（可选） | |
使用环境变量的示例用法：
```bash
# 设置环境变量
export LOG_LEVEL="debug"
export REQUEST_TIMEOUT_MS="15000"
export TFC_TOKEN="your-terraform-cloud-token"
# 运行服务器
npm start
```
## 测试
有关测试该项目的信息，请参阅 [TESTS.md](TESTS.md) 文件。
MCP 市场
