Terraform Registry MCP Server

Terraform Registry MCP Server

Um servidor Model Context Protocol (MCP) que fornece ferramentas para interagir com a API do Terraform Registry. Este servidor permite que agentes de IA consultem informações de provedores, detalhes de recursos e metadados de módulos.

[!IMPORTANT] Este projeto foi usado como uma PoC para um novo servidor MCP oficial do Terraform. Este repositório foi arquivado em favor daquele.

Instalação

Instalando no Cursor

Para instalar e usar este servidor MCP no Cursor:

1. No Cursor, abra as Configurações (⌘+,) e navegue até a aba "MCP".

2. Clique em "+ Adicionar novo servidor MCP."

3. Insira o seguinte:

   • Nome: terraform-registry
   • Tipo: comando
   • Comando: npx -y terraform-mcp-server

4. Clique em "Adicionar" e depois role até o servidor e clique em "Desativado" para habilitar o servidor.

5. Reinicie o Cursor, se necessário, para garantir que o servidor MCP seja carregado corretamente.

Instalando no Claude Desktop

Para instalar e usar este servidor MCP no Claude Desktop:

1. No Claude Desktop, abra as Configurações (⌘+,) e navegue até a aba "Desenvolvedor".

2. Clique em "Editar Configuração" na parte inferior da janela.

3. Edite o arquivo (~/Library/Application Support/Claude/claude_desktop_config.json) para adicionar o seguinte código e salve o arquivo.

{
  "mcpServers": {
    "terraform-registry": {
      "command": "npx",
      "args": ["-y", "terraform-mcp-server"]
    }
  }
}

4. Reinicie o Claude Desktop para garantir que o servidor MCP seja carregado corretamente.

Ferramentas

As seguintes ferramentas estão disponíveis neste servidor MCP:

Ferramentas Principais do Registry

Ferramenta	Descrição
providerDetails	Obtém informações detalhadas sobre um provedor do Terraform
resourceUsage	Obtém exemplos de uso de um recurso do Terraform e recursos relacionados
moduleSearch	Pesquisa e recomenda módulos do Terraform com base em uma consulta
listDataSources	Lista todas as fontes de dados disponíveis para um provedor e seus detalhes básicos
resourceArgumentDetails	Busca detalhes abrangentes sobre os argumentos de um tipo de recurso
moduleDetails	Recupera metadados detalhados de um módulo do Terraform
functionDetails	Obtém detalhes sobre uma função de provedor do Terraform
providerGuides	Lista e visualiza guias e documentações específicas do provedor
policySearch	Pesquisa bibliotecas de políticas no Terraform Registry
policyDetails	Obtém informações detalhadas sobre uma biblioteca de políticas específica

Ferramentas do Terraform Cloud

Estas ferramentas exigem um token da API do Terraform Cloud (TFC_TOKEN):

Ferramenta	Descrição
listOrganizations	Lista todas as organizações às quais o usuário autenticado tem acesso
privateModuleSearch	Pesquisa módulos privados em uma organização
privateModuleDetails	Obtém informações detalhadas sobre um módulo privado
explorerQuery	Consulta a API Explorer do Terraform Cloud para analisar dados
listWorkspaces	Lista workspaces em uma organização
workspaceDetails	Obtém informações detalhadas sobre um workspace específico
lockWorkspace	Bloqueia um workspace para impedir execuções
unlockWorkspace	Desbloqueia um workspace para permitir execuções
listRuns	Lista execuções de um workspace
runDetails	Obtém informações detalhadas sobre uma execução específica
createRun	Cria uma nova execução para um workspace
applyRun	Aplica uma execução que foi planejada
cancelRun	Cancela uma execução em andamento
listWorkspaceResources	Lista recursos em um workspace

Recursos

O servidor MCP suporta os seguintes URIs de recursos para listagem e leitura por meio dos métodos resources/*:

Tipo de Recurso	URI(s) de Exemplo	Descrição
Provedores	terraform:providers	Lista todos os namespaces/provedores
	terraform:provider:<namespace>/<name>	Obtém detalhes de um provedor específico
Versões de Provedores	terraform:provider:<namespace>/<name>/versions	Lista as versões disponíveis para um provedor
Recursos de Provedores	terraform:provider:<namespace>/<name>/resources	Lista recursos de um provedor
	terraform:resource:<namespace>/<name>/<resource_name>	Obtém detalhes de um tipo de recurso específico
Fontes de Dados de Provedores	terraform:provider:<namespace>/<name>/dataSources	Lista fontes de dados de um provedor
	terraform:dataSource:<namespace>/<name>/<data_source_name>	Obtém detalhes de uma fonte de dados específica
Funções de Provedores	terraform:provider:<namespace>/<name>/functions	Lista funções de um provedor
	terraform:function:<namespace>/<name>/<function_name>	Obtém detalhes de uma função específica

O servidor também suporta resources/templates/list para fornecer modelos para criar:

• terraform:provider
• terraform:resource
• terraform:dataSource

Prompts

Os seguintes prompts estão disponíveis para gerar respostas contextuais:

Prompt	Descrição	Argumentos Obrigatórios
migrate-clouds	Gera código Terraform para migrar infraestrutura entre provedores de nuvem	sourceCloud, targetCloud, terraformCode
generate-resource-skeleton	Ajuda os usuários a criar rapidamente novos recursos do Terraform com boas práticas	resourceType
optimize-terraform-module	Fornece recomendações acionáveis para melhorar o código Terraform	terraformCode
migrate-provider-version	Auxilia com atualizações de versão de provedores e mudanças que quebram compatibilidade	providerName, currentVersion, targetVersion, terraformCode (opcional)
analyze-workspace-runs	Analisa falhas recentes de execução e fornece orientação de solução de problemas para workspaces do Terraform Cloud	workspaceId, runsToAnalyze (opcional, padrão: 5)

Problemas Conhecidos com Prompts

Nota: Há um problema conhecido com a funcionalidade getPrompt que pode causar falhas no servidor. O servidor registra corretamente os prompts e pode listá-los, mas solicitações diretas usando o método getPrompt podem causar problemas de conectividade. Isso está sendo investigado e pode estar relacionado à compatibilidade do SDK ou a detalhes de implementação. Até que seja resolvido, use listPrompts para ver os prompts disponíveis, mas evite chamadas diretas de getPrompt.

Executando o Servidor

O servidor é executado usando transporte stdio para comunicação MCP:

npm install
npm start

Configuração com Variáveis de Ambiente

O servidor pode ser configurado usando variáveis de ambiente:

Variável de Ambiente	Descrição	Valor Padrão
TERRAFORM_REGISTRY_URL	URL base para a API do Terraform Registry	https://registry.terraform.io
DEFAULT_PROVIDER_NAMESPACE	Namespace padrão para provedores	hashicorp
LOG_LEVEL	Nível de registro (error, warn, info, debug)	info
REQUEST_TIMEOUT_MS	Tempo limite para solicitações de API em milissegundos	10000
RATE_LIMIT_ENABLED	Habilita limitação de taxa para solicitações de API	false
RATE_LIMIT_REQUESTS	Número de solicitações permitidas na janela de tempo	60
RATE_LIMIT_WINDOW_MS	Janela de tempo para limitação de taxa em milissegundos	60000
TFC_TOKEN	Token da API do Terraform Cloud para acesso ao registry privado (opcional)

Exemplo de uso com variáveis de ambiente:

# Set environment variables
export LOG_LEVEL="debug"
export REQUEST_TIMEOUT_MS="15000"
export TFC_TOKEN="your-terraform-cloud-token"

# Run the server
npm start

Testes

Consulte o arquivo TESTS.md para obter informações sobre como testar este projeto.