Terrakube

Terrakube MCP Server provides a typed, API-driven interface for managing Terrakube workspaces, variables, modules, and organizations through a Model Context Protocol (MCP) server. It enables automated workspace lifecycle, centralized variable handling, module operations, and org management with robust error handling and environment-based configuration.

How to use

You interact with the Terrakube MCP Server through an MCP client that talks to either a remote HTTP endpoint or a local stdio server. The server exposes functions to create, read, update, and delete workspaces, variables, modules, and organizations, and returns structured details for each operation. Use the appropriate client calls to manage Terrakube resources in your automation, CI pipelines, or tooling.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system. You will also need access to a Terrakube instance with a valid API URL and a personal access token (PAT) for authentication.

# Option A: Install via Smithery (auto-setup for Claude Desktop)
npx -y @smithery/cli install @AzBuilder/mcp-server-terrakube --client claude

# Option B: Development setup (clone, install, build)
git clone https://github.com/azbuilder/terrakube-mcp-server.git
cd terrakube-mcp-server
npm install
npm run build

# Ensure you have a .env with API details if running locally

Usage with Claude Desktop

To run the Terrakube MCP Server from Claude Desktop, configure the MCP server entry with the stdio runtime and the required environment variables. The following example shows how to wire the server so Claude Desktop can invoke it via npm.

{
  "mcpServers": {
    "terrakube": {
      "command": "npx",
      "args": ["-y", "@terrakube/mcp-server"],
      "env": {
        "TERRAKUBE_API_URL": "<YOUR_API_URL>",
        "TERRAKUBE_PAT_TOKEN": "<YOUR_PAT_TOKEN>"
      }
    }
  }
}

Available tools

createWorkspace

Create a new workspace in Terrakube with a name, organization, and optional metadata such as description, VCS provider ID, repository, and branch.

updateWorkspace

Update details of an existing workspace, including its description and VCS configuration.

deleteWorkspace

Remove a workspace by name within an organization, returning a success status.

getWorkspace

Fetch details for a specific workspace by name and organization.

listWorkspaces

List all workspaces within an organization.

createVariable

Create a new variable inside a workspace with attributes like value, description, category, HCL flag, and sensitivity.

updateVariable

Update an existing variable's value and metadata within a workspace.

deleteVariable

Delete a variable from a workspace and organization.

getVariable

Retrieve details for a specific variable in a workspace.

listVariables

List all variables in a workspace.

createModule

Create a new module with provider information and an optional description.

updateModule

Update the details of an existing module, including its description and provider.

deleteModule

Delete a module by name, organization, and provider.

getModule

Get details for a specific module.

listModules

List all modules within an organization.

createOrganization

Create a new organization with an optional description.

updateOrganization

Update an organization's description.

deleteOrganization

Delete an organization by name.

getOrganization

Fetch details of a specific organization.

listOrganizations

List all organizations.