# Terraform Modules MCP Server

A multi-cloud MCP server that lets AI assistants discover, understand, and generate Terraform code from module catalogs across AWS, Azure, and GCP.

## What it does

- **Discover modules** — list modules across all clouds with descriptions, dependencies, and costs
- **Understand wiring** — see how modules connect (e.g., VPC outputs feed into EKS inputs)
- **Estimate costs** — get per-module cost breakdowns by tier (dev/staging/prod)
- **Generate code** — produce ready-to-use `.tf` files for single modules or full stacks

## Quick start

### Install via Claude Code

Add to your `~/.mcp.json` (global) or `.claude/mcp.json` (per-project):

```json
{
  "mcpServers": {
    "tf-modules": {
      "command": "uvx",
      "args": ["tf-mcp"],
      "env": {
        "TF_MODULES_AWS_DIR": "/path/to/your/aws-tf/modules",
        "TF_MODULES_AZURE_DIR": "/path/to/your/azure-tf/modules",
        "TF_MODULES_GCP_DIR": "/path/to/your/gcp-tf/modules"
      }
    }
  }
}
```

Only include the `env` entries for clouds you have modules for.

### Install via pip

```bash
pip install tf-mcp
```

### Run standalone

```bash
tf-mcp
```

## Prerequisites

- Python >= 3.11
- One or more directories containing Terraform modules

## Module directory layout

Point the server at directories containing Terraform modules. Each module should be a subdirectory with at least a `main.tf`:

```
your-modules-dir/
  vpc/
    main.tf
    variables.tf
    outputs.tf
  eks-cluster/
    main.tf
    variables.tf
    outputs.tf
```

The server auto-discovers all subdirectories containing a `main.tf`.

## Configuration

Tell the server where your modules live using environment variables:

| Variable | Description |
|----------|-------------|
| `TF_MODULES_AWS_DIR` | Path to AWS `modules/` directory |
| `TF_MODULES_AZURE_DIR` | Path to Azure `modules/` directory |
| `TF_MODULES_GCP_DIR` | Path to GCP `modules/` directory |

If no env vars are set, the server looks for sibling repos in the default layout:

```
parent-dir/
  aws-tf/modules/
  azure-tf/modules/
  gcp-tf/modules/
  tf-mcp-server/        # this repo
```

## Tools

| Tool | Description |
|------|-------------|
| `list_modules` | List modules with optional cloud filter |
| `get_module_details` | Full variable/output/cost reference for one module |
| `get_module_dependencies` | Dependency graph and output-to-input wiring |
| `estimate_costs` | Cost estimates for a set of modules by tier |
| `generate_module_code` | Generate `.tf` for a single module |
| `generate_stack_code` | Generate a complete multi-module stack with auto-wiring |

## Resources

| URI | Description |
|-----|-------------|
| `modules://catalog` | Full listing across all clouds |
| `modules://{cloud}/catalog` | Listing for one cloud |
| `modules://{cloud}/{name}/readme` | Module README.md |
| `modules://{cloud}/{name}/examples` | Module examples/main.tf |
| `modules://{cloud}/dependency-graph` | Text dependency graph |
| `modules://conventions` | Terraform conventions |

## Development

```bash
git clone https://github.com/m-ujifusa/tf-mcp-server.git
cd tf-mcp-server
uv sync
uv run tf-mcp
```

## License

MIT
