Terramate Mcp Server

Terramate MCP Server

[](https://github.com/terramate-io/terramate-mcp-server/actions/workflows/ci.yml) [](https://goreportcard.com/report/github.com/terramate-io/terramate-mcp-server) [](https://opensource.org/licenses/MIT)

The Terramate MCP Server integrates Terramate CLI and Terramate Cloud with AI assistants like ChatGPT, Claude, Cursor, and any LLM that supports the Model Context Protocol (MCP).

This server enables natural language interactions with your Terramate Cloud organization, allowing you to query deployments, stacks, drifts, and manage Infrastructure as Code (IaC) workflows directly from your AI assistant.

Features

• 📚 Stack Management - List, filter, and query stacks with powerful search capabilities
• 🔍 Drift Detection - View drift runs and retrieve terraform plan outputs for AI-assisted reconciliation
• 🔀 Pull Request Integration - Review terraform plans for all stacks in PRs/MRs before merging
• 🚢 Deployment Tracking - Monitor CI/CD deployments, view terraform apply output, debug failures
• 🛠️ MCP Tools - 13 production-ready tools for Terramate Cloud operations
• 📦 Stack Resources - List and filter resources per stack (plan/state) by status, type, provider, and more

Installation

Prerequisites

• Go 1.25.0 or later
• A Terramate Cloud account
• Authentication credentials:
• Recommended: Run terramate cloud login (self-service, no admin required)
• Alternative: Organization API key (requires admin to generate)

From Source

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

The binary will be available at bin/terramate-mcp-server.

Using Docker

Pull the pre-built image from GitHub Container Registry:

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

# Run with JWT authentication (recommended)
# First: terramate cloud login
docker run --rm -it \
  -v ~/.terramate.d:/root/.terramate.d:ro \
  -e TERRAMATE_REGION="eu" \
  ghcr.io/terramate-io/terramate-mcp-server:latest

# Or with API key (issuing an organization 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

> Apple Silicon (M1/M2/M3/M4): The Docker image is built for linux/amd64. On Apple Silicon Macs you must pass --platform linux/amd64 to docker run (and docker pull). Docker Desktop will run the image via Rosetta emulation automatically. See the [Claude Desktop](#claude-desktop) and [Cursor](#cursor) integration examples below for ready-to-use configurations.

Or build locally:

# Build with default version info
docker build -t terramate-mcp-server .

# Build with custom version information
docker build . \
  --build-arg VERSION=1.0.0 \
  --build-arg GIT_COMMIT=$(git rev-parse --short HEAD) \
  --build-arg BUILD_TIME=$(date -u '+%Y-%m-%d_%H:%M:%S') \
  -t terramate-mcp-server:1.0.0

# Run with JWT authentication (recommended)
docker run --rm -it \
  -v ~/.terramate.d:/root/.terramate.d:ro \
  -e TERRAMATE_REGION="eu" \
  terramate-mcp-server:latest

# Or with API key (deprecated)
docker run --rm -it \
  -e TERRAMATE_API_KEY="your-api-key" \
  -e TERRAMATE_REGION="eu" \
  terramate-mcp-server:latest

Docker Build Arguments:

| Argument | Description | Default | | ------------ | ------------------------------ | --------- | | VERSION | Version to embed in the binary | dev | | GIT_COMMIT | Git commit SHA to embed | unknown | | BUILD_TIME | Build timestamp to embed | unknown |

Authentication

The MCP server supports two authentication methods: JWT Token (recommended) and API Key (requires admin privileges).

JWT Token Authentication (Recommended)

JWT tokens provide user-level authentication using your Terramate Cloud credentials obtained via terramate cloud login.

Why JWT is Preferred:

• ✅ Self-service: Any user can authenticate themselves without admin intervention
• ✅ No admin required: Unlike organization API keys which require admin privileges to create
• ✅ User-level permissions: Actions are tracked per user for better audit trails
• ✅ Multiple providers: Google, GitHub, GitLab, SSO support
• ✅ Automatic token refresh: Tokens refresh transparently when expired - zero maintenance
• ✅ No manual credential management: Simple terramate cloud login command

Benefits:

• User-level permissions and audit trails
• Support for multiple authentication providers (Google, GitHub, GitLab, SSO)
• Automatic token management via Terramate CLI
• No manual credential management
• No organization admin required - users can self-authenticate

Setup:

1. Login via Terramate CLI:

``bash terramate cloud login ` This opens your browser and stores JWT credentials in ~/.terramate.d/credentials.tmrc.json`

1. Run the MCP server (auto-detects credentials):

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

1. Or specify custom credential file location:

``bash ./bin/terramate-mcp-server --credential-file /path/to/credentials.tmrc.json --region eu ``

Credential File Location:

• Default: ~/.terramate.d/credentials.tmrc.json
• Custom: Set via --credential-file flag or TERRAMATE_CREDENTIAL_FILE environment variable

Supported Providers:

• Google OAuth
• GitHub OAuth
• GitLab OAuth
• SSO

Token Expiration: JWT tokens typically expire after 1 hour. The MCP server handles this automatically:

• Automatic Refresh: When a token expires, the server automatically refreshes it using the refresh token
• CLI-Compatible IDP Key: Refresh uses the same Firebase IDP key as Terramate CLI by default, so tokens issued by terramate cloud login can be refreshed correctly
• Optional Override: Set TMC_API_IDP_KEY to override the default IDP key (advanced/debug use)
• File Watching: The server watches the credential file and automatically reloads tokens when the Terramate CLI updates them
• Zero Downtime: Token refresh happens transparently - no need to restart the server
• Shared Credentials: Both MCP server and Terramate CLI can safely use and update the same credential file

How it works:

1. Initial setup: Run terramate cloud login once
2. MCP server starts and loads the JWT token
3. Server automatically watches the credential file for changes
4. When you use Terramate CLI, it may refresh the token
5. MCP server detects the file change and reloads the new token
6. If MCP server gets a 401 error, it refreshes the token itself
7. Everything happens automatically - zero maintenance!

API Key Authentication

API keys provide organization-level authentication.

⚠️ Requires Admin Privileges: Organization API keys can only be created and managed by organization administrators in Terramate Cloud. Regular users cannot generate API keys, making JWT authentication the preferred method for individual developers.

Setup:

./bin/terramate-mcp-server --api-key "your-api-key" --region eu

Or with environment variable:

export TERRAMATE_API_KEY="your-api-key"
export TERRAMATE_REGION="eu"
./bin/terramate-mcp-server

Obtain API Key (Requires Admin): Organization administrators can generate API keys from Terramate Cloud Settings

Authentication Priority

When both authentication methods are available, the MCP server uses this precedence:

1. API Key (if --api-key flag or TERRAMATE_API_KEY env var is set)
2. JWT Token from credential file

This ensures backward compatibility while allowing migration to JWT authentication.

Configuration

The server accepts configuration via command-line flags or environment variables:

| Flag | Environment Variable | Required | Default | Description | | -------------------- | --------------------------- | -------- | ------------------------------------------------- | ------------------------------------------------------------------ | | --api-key | TERRAMATE_API_KEY | ❌ | - | Terramate Cloud API key (deprecated, prefer JWT authentication) | | --credential-file | TERRAMATE_CREDENTIAL_FILE | ❌ | ~/.terramate.d/credentials.tmrc.json | Path to JWT credentials file | | --region | TERRAMATE_REGION | ⚠️\* | - | Terramate Cloud region (eu or us) | | --base-url | TERRAMATE_BASE_URL | ❌ | https://api.terramate.io | Custom API base URL |

\* Required when using the default base URL. Optional if --base-url is specified.

Region Endpoints

• EU: https://api.terramate.io (default)
• US: https://api.us.terramate.io

When using --region eu, the server automatically uses the EU endpoint. When using --region us, it uses the US endpoint.

Usage

Running the Server

Standalone Mode

With JWT Authentication (Recommended):

# First, login via Terramate CLI
terramate cloud login

# Run MCP server (auto-loads credentials)
./bin/terramate-mcp-server --region eu

# Or specify custom credential file
./bin/terramate-mcp-server --credential-file /path/to/credentials.tmrc.json --region eu

# Custom base URL (bypasses region)
./bin/terramate-mcp-server --base-url="https://custom.api.example.com"

With API Key:

# Using environment variables
export TERRAMATE_API_KEY="your-api-key"
export TERRAMATE_REGION="eu"
./bin/terramate-mcp-server

# Using command-line flags
./bin/terramate-mcp-server --api-key="your-api-key" --region="eu"

With Docker

> Apple Silicon: Add --platform linux/amd64 to all docker run commands below.

With JWT Authentication:

# Mount credential file from host
docker run --rm -it \
  --platform linux/amd64 \
  -v ~/.terramate.d:/root/.terramate.d:ro \
  -e TERRAMATE_REGION="eu" \
  ghcr.io/terramate-io/terramate-mcp-server:latest

With API Key:

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

Integrating with AI Assistants

The server communicates via stdio using the Model Context Protocol. Configure your AI assistant to use this server:

Claude Desktop

With JWT Authentication (Recommended):

Option 1: Direct Binary

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "terramate": {
      "command": "/path/to/bin/terramate-mcp-server",
      "args": ["--region", "eu"]
    }
  }
}

Option 2: With Pre-Start Refresh (Recommended for reliability)

Ensures token is fresh before server starts:

{
  "mcpServers": {
    "terramate": {
      "command": "bash",
      "args": [
        "-c",
        "terramate cloud info -v >/dev/null 2>&1 || true; /path/to/bin/terramate-mcp-server --region eu"
      ]
    }
  }
}

Note: Claude Desktop runs in your user context, so it automatically has access to ~/.terramate.d/credentials.tmrc.json. The MCP server now includes automatic token refresh, so the pre-start command is optional but recommended for extra reliability.

Option 3: Docker

Runs the MCP server via Docker instead of a local binary. On Apple Silicon Macs, the --platform linux/amd64 flag is required:

{
  "mcpServers": {
    "terramate": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--platform", "linux/amd64",
        "-v", "~/.terramate.d:/root/.terramate.d:ro",
        "-e", "TERRAMATE_REGION=eu",
        "ghcr.io/terramate-io/terramate-mcp-server:latest"
      ]
    }
  }
}

> Note: On Intel-based Macs and Linux x86_64 hosts the --platform linux/amd64 flag is optional but harmless to include.

With API Key:

{
  "mcpServers": {
    "terramate": {
      "command": "/path/to/terramate-mcp-server",
      "env": {
        "TERRAMATE_API_KEY": "your-api-key",
        "TERRAMATE_REGION": "eu"
      }
    }
  }
}

Cursor

With JWT Authentication (Recommended):

Option 1: Direct Binary

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "terramate": {
      "command": "/path/to/bin/terramate-mcp-server",
      "args": ["--region", "eu"]
    }
  }
}

Option 2: Docker

Runs the MCP server via Docker. On Apple Silicon Macs, the --platform linux/amd64 flag is required:

{
  "mcpServers": {
    "terramate": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--platform", "linux/amd64",
        "-v", "~/.terramate.d:/root/.terramate.d:ro",
        "-e", "TERRAMATE_REGION=eu",
        "ghcr.io/terramate-io/terramate-mcp-server:latest"
      ]
    }
  }
}

> Note: On Intel-based Macs and Linux x86_64 hosts the --platform linux/amd64 flag is optional but harmless to include.

Option 3: Docker with Pre-Start Refresh (Optional)

Ensures token is fresh before server starts:

{
  "mcpServers": {
    "terramate": {
      "command": "bash",
      "args": [
        "-c",
        "terramate cloud info -v >/dev/null 2>&1 || true; docker run -i --rm --platform linux/amd64 -v ~/.terramate.d:/root/.terramate.d:ro -e TERRAMATE_REGION=eu ghcr.io/terramate-io/terramate-mcp-server:latest"
      ]
    }
  }
}

Note: The MCP server now includes automatic token refresh and file watching. The pre-start terramate cloud info command is optional but provides extra reliability by ensuring the token is fresh before the server starts.

With API Key (Legacy):

{
  "mcpServers": {
    "terramate": {
      "command": "/path/to/bin/terramate-mcp-server",
      "args": ["--api-key", "your-api-key", "--region", "eu"]
    }
  }
}

Available Tools

The MCP server provides the following tools for interacting with Terramate Cloud:

Authentication

tmc_authenticate

Authenticates with Terramate Cloud and retrieves organization membership information.

Parameters: None (uses configured API key)

Returns: Organization membership details including UUIDs needed for other tools

Example:

User: "Show me my Terramate organizations"
Assistant: *calls tmc_authenticate*
Result: List of organizations with UUIDs and roles

---

Stack Management

tmc_list_stacks

Lists stacks in an organization with powerful filtering and pagination.

Required Parameters:

• organization_uuid (string) - Organization UUID from tmc_authenticate

Optional Filters:

• repository (array) - Filter by repository URLs
• target (array) - Filter by target environment
• status (array) - Filter by status (ok, failed, drifted, etc.)
• deployment_status (array) - Filter by deployment status
• drift_status (array) - Filter by drift status (ok, drifted, failed)
• draft (boolean) - Filter by draft status
• is_archived (array) - Filter by archived status
• search (string) - Substring search on name, ID, description, path
• meta_id (string) - Filter by exact meta ID
• meta_tag (array) - Filter by tags
• deployment_uuid (string) - Filter by deployment UUID
• policy_severity (array) - Filter by policy severity
• page (number) - Page number (default: 1)
• `per_p

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: terramate-io
• Source: terramate-io/terramate-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.