terraform-mcp-server

# Terraform Registry MCP Server A Model Context Protocol (MCP) server that provides tools for interacting with the Terraform Registry API. This server enables AI agents to query provider information, resource details, and module metadata. > [!IMPORTANT] > This project was used as a PoC for a new official [Terraform MCP server](https://github.com/hashicorp/terraform-mcp-server). This repo has been archived in favor of that one. ## Installation ### Installing in Cursor To install and use this MCP server in [Cursor](https://cursor.sh/): 1. In Cursor, open Settings (⌘+,) and navigate to the "MCP" tab. 2. Click "+ Add new MCP server." 3. Enter the following: - Name: terraform-registry - Type: command - Command: npx -y terraform-mcp-server 4. Click "Add" then scroll to the server and click "Disabled" to enable the server. 5. Restart Cursor, if needed, to ensure the MCP server is properly loaded.  ### Installing in Claude Desktop To install and use this MCP server in Claude Desktop: 1. In Claude Desktop, open Settings (⌘+,) and navigate to the "Developer" tab. 2. Click "Edit Config" at the bottom of the window. 3. Edit the file (`~/Library/Application Support/Claude/claude_desktop_config.json`) to add the following code, then Save the file. ```json { "mcpServers": { "terraform-registry": { "command": "npx", "args": ["-y", "terraform-mcp-server"] } } } ``` 4. Restart Claude Desktop to ensure the MCP server is properly loaded. ## Tools The following tools are available in this MCP server: ### Core Registry Tools | Tool | Description | |------|-------------| | `providerDetails` | Gets detailed information about a Terraform provider | | `resourceUsage` | Gets example usage of a Terraform resource and related resources | | `moduleSearch` | Searches for and recommends Terraform modules based on a query | | `listDataSources` | Lists all available data sources for a provider and their basic details | | `resourceArgumentDetails` | Fetches comprehensive details about a resource type's arguments | | `moduleDetails` | Retrieves detailed metadata for a Terraform module | | `functionDetails` | Gets details about a Terraform provider function | | `providerGuides` | Lists and views provider-specific guides and documentation | | `policySearch` | Searches for policy libraries in the Terraform Registry | | `policyDetails` | Gets detailed information about a specific policy library | ### Terraform Cloud Tools These tools require a Terraform Cloud API token (`TFC_TOKEN`): | Tool | Description | |------|-------------| | `listOrganizations` | Lists all organizations the authenticated user has access to | | `privateModuleSearch` | Searches for private modules in an organization | | `privateModuleDetails` | Gets detailed information about a private module | | `explorerQuery` | Queries the Terraform Cloud Explorer API to analyze data | | `listWorkspaces` | Lists workspaces in an organization | | `workspaceDetails` | Gets detailed information about a specific workspace | | `lockWorkspace` | Locks a workspace to prevent runs | | `unlockWorkspace` | Unlocks a workspace to allow runs | | `listRuns` | Lists runs for a workspace | | `runDetails` | Gets detailed information about a specific run | | `createRun` | Creates a new run for a workspace | | `applyRun` | Applies a run that's been planned | | `cancelRun` | Cancels a run that's in progress | | `listWorkspaceResources` | Lists resources in a workspace | ## Resources The MCP server supports the following resource URIs for listing and reading via the `resources/*` methods: | Resource Type | Example URI(s) | Description | |---------------|----------------|-------------| | **Providers** | `terraform:providers` | List all namespaces/providers | | | `terraform:provider:<namespace>/<name>` | Get details for a specific provider | | **Provider Versions** | `terraform:provider:<namespace>/<name>/versions` | List available versions for a provider | | **Provider Resources** | `terraform:provider:<namespace>/<name>/resources` | List resources for a provider | | | `terraform:resource:<namespace>/<name>/<resource_name>` | Get details for a specific resource type | | **Provider Data Sources** | `terraform:provider:<namespace>/<name>/dataSources` | List data sources for a provider | | | `terraform:dataSource:<namespace>/<name>/<data_source_name>` | Get details for a specific data source | | **Provider Functions** | `terraform:provider:<namespace>/<name>/functions` | List functions for a provider | | | `terraform:function:<namespace>/<name>/<function_name>` | Get details for a specific function | The server also supports `resources/templates/list` to provide templates for creating: - `terraform:provider` - `terraform:resource` - `terraform:dataSource` ## Prompts The following prompts are available for generating contextual responses: | Prompt | Description | Required Arguments | |--------|-------------|-------------------| | `migrate-clouds` | Generate Terraform code to migrate infrastructure between cloud providers | `sourceCloud`, `targetCloud`, `terraformCode` | | `generate-resource-skeleton` | Helps users quickly scaffold new Terraform resources with best practices | `resourceType` | | `optimize-terraform-module` | Provides actionable recommendations for improving Terraform code | `terraformCode` | | `migrate-provider-version` | Assists with provider version upgrades and breaking changes | `providerName`, `currentVersion`, `targetVersion`, `terraformCode` (optional) | | `analyze-workspace-runs` | Analyzes recent run failures and provides troubleshooting guidance for Terraform Cloud workspaces | `workspaceId`, `runsToAnalyze` (optional, default: 5) | ### Known Issues with Prompts **Note**: There is a known issue with the `getPrompt` functionality that can cause server crashes. The server properly registers prompts and can list them, but direct requests using the `getPrompt` method may cause connectivity issues. This is being investigated and may be related to SDK compatibility or implementation details. Until resolved, use `listPrompts` to see available prompts but avoid direct `getPrompt` calls. ## Running the Server The server runs using stdio transport for MCP communication: ```bash npm install npm start ``` ### Configuration with Environment Variables The server can be configured using environment variables: | Environment Variable | Description | Default Value | |---------------------|-------------|---------------| | `TERRAFORM_REGISTRY_URL` | Base URL for Terraform Registry API | https://registry.terraform.io | | `DEFAULT_PROVIDER_NAMESPACE` | Default namespace for providers | hashicorp | | `LOG_LEVEL` | Logging level (error, warn, info, debug) | info | | `REQUEST_TIMEOUT_MS` | Timeout for API requests in milliseconds | 10000 | | `RATE_LIMIT_ENABLED` | Enable rate limiting for API requests | false | | `RATE_LIMIT_REQUESTS` | Number of requests allowed in time window | 60 | | `RATE_LIMIT_WINDOW_MS` | Time window for rate limiting in milliseconds | 60000 | | `TFC_TOKEN` | Terraform Cloud API token for private registry access (optional) | | Example usage with environment variables: ```bash # Set environment variables export LOG_LEVEL="debug" export REQUEST_TIMEOUT_MS="15000" export TFC_TOKEN="your-terraform-cloud-token" # Run the server npm start ``` ## Testing See the [TESTS.md](TESTS.md) file for information about testing this project.