terramate

The Terramate MCP Server provides an interface to interact with Terramate Cloud and the Terramate CLI through the Model Context Protocol (MCP). It enables natural language queries and AI-assisted workflows for managing stacks, deployments, drift detection, and pull-request related Terraform plans. You can query stacks, view drift runs, fetch Terraform plan outputs for AI-assisted reconciliation, and review Terraform plans across multiple stacks during PRs or MRs. By leveraging authentication via JWT tokens or API keys, the server ensures actions are performed under appropriate permissions and can automatically refresh credentials as needed. Tools exposed by the MCP server cover common Terramate Cloud operations and IaC workflows, giving AI assistants a rich set of capabilities to reason about infrastructure state and changes.

Prerequisites:

• Docker (recommended) or Go toolchain if building from source
• Terramate Cloud account and credentials (login via Terramate CLI)
• Optional: admin privileges if you plan to use organization API keys

From Docker (recommended):

1. Pull and run the image (example with region EU):

# Pull the latest image
docker pull ghcr.io/terramate-io/terramate-mcp-server:latest

# Run with JWT authentication (recommended); adjust volume paths as needed
docker run --rm -it \
  -v ~/.terramate.d:/root/.terramate.d:ro \
  -e TERRAMATE_REGION="eu" \
  ghcr.io/terramate-io/terramate-mcp-server:latest

2. Or run with API key (requires admin privileges):

docker run --rm -it \
  -e TERRAMATE_API_KEY="your-api-key" \
  -e TERRAMATE_REGION="eu" \
  ghcr.io/terramate-io/terramate-mcp-server:latest

From Source (Go build):

1. Clone the repo and build:

git clone https://github.com/terramate-io/terramate-mcp-server.git
cd terramate-mcp-server
make build

2. Run the binary directly:

./bin/terramate-mcp-server --region eu

Prerequisites for building from source:

• Go 1.20+ (or the version specified by the project's go.mod)
• A Terramate Cloud account and credentials file if using JWT authentication

Environment configuration:

• TERRAMATE_REGION: Region for Terramate Cloud (e.g., eu)
• TERRAMATE_API_KEY: Optional API key for organization-level auth (admin required)
• TERRAMATE_CREDENTIAL_FILE: Path to a credentials file if not using default location

Note: If you are developing locally, ensure your Terramate CLI is installed and configured, since the MCP server interacts with Terramate Cloud via the CLI and API keys.

Tips and common issues:

• Authentication: JWT (via terramate cloud login) is recommended for end-user access. API keys require admin privileges. The MCP server automatically refreshes JWT tokens and reloads credential files on changes.
• Token management: If you see a 401, the server will attempt to refresh automatically; ensure your credential file is accessible and up to date.
• Docker considerations: On Apple Silicon (M1/M2/M3/M4), the terramate-mcp-server image is linux/amd64. Use --platform linux/amd64 when pulling/running on Apple Silicon if needed.
• Credential file location: Default is ~/.terramate.d/credentials.tmrc.json. You can override with TERRAMATE_CREDENTIAL_FILE or --credential-file when starting the server.
• Logs and troubleshooting: Look for messages about credential loading, token refresh, and MCP tool initialization to diagnose authentication or capability issues quickly.