Terraform Cloud MCP Server

Instructions

Implementation Reference

• src/index.ts:137-162 (handler)

  Handler function that lists all workspaces in the specified Terraform Cloud organization by calling the tfCloudRequest helper to fetch data from the API, maps it to the output format, and handles errors.

  async ({ organization }) => {
    try {
      const data = await tfCloudRequest(`/organizations/${organization}/workspaces`);
      
      const workspaces = data.data.map((ws: any) => ({
        id: ws.id,
        name: ws.attributes.name,
        locked: ws.attributes.locked,
        executionMode: ws.attributes['execution-mode'],
        currentRunStatus: ws.relationships['current-run']?.data ? 'active' : 'idle'
      }));
  
      const output = { workspaces };
  
      return {
        content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
        structuredContent: output
      };
    } catch (error) {
      const errorMsg = error instanceof Error ? error.message : String(error);
      return {
        content: [{ type: 'text', text: `Error: ${errorMsg}` }],
        isError: true
      };
    }
  }

• src/index.ts:122-136 (schema)

  Input and output schema definitions for the list_workspaces tool using Zod validation.

    title: 'List Workspaces',
    description: 'List all workspaces in a Terraform Cloud organization',
    inputSchema: {
      organization: z.string().default('urbanmedia').describe('Organization name')
    },
    outputSchema: {
      workspaces: z.array(z.object({
        id: z.string(),
        name: z.string(),
        locked: z.boolean(),
        executionMode: z.string(),
        currentRunStatus: z.string().optional()
      }))
    }
  },

• src/index.ts:120-163 (registration)

  Registration of the list_workspaces tool on the MCP server, including name, schema, and handler function.

    'list_workspaces',
    {
      title: 'List Workspaces',
      description: 'List all workspaces in a Terraform Cloud organization',
      inputSchema: {
        organization: z.string().default('urbanmedia').describe('Organization name')
      },
      outputSchema: {
        workspaces: z.array(z.object({
          id: z.string(),
          name: z.string(),
          locked: z.boolean(),
          executionMode: z.string(),
          currentRunStatus: z.string().optional()
        }))
      }
    },
    async ({ organization }) => {
      try {
        const data = await tfCloudRequest(`/organizations/${organization}/workspaces`);
        
        const workspaces = data.data.map((ws: any) => ({
          id: ws.id,
          name: ws.attributes.name,
          locked: ws.attributes.locked,
          executionMode: ws.attributes['execution-mode'],
          currentRunStatus: ws.relationships['current-run']?.data ? 'active' : 'idle'
        }));
  
        const output = { workspaces };
  
        return {
          content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
          structuredContent: output
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        return {
          content: [{ type: 'text', text: `Error: ${errorMsg}` }],
          isError: true
        };
      }
    }
  );

• src/index.ts:25-39 (helper)

  Helper function to make authenticated requests to the Terraform Cloud API, used by the list_workspaces handler.

  async function tfCloudRequest(endpoint: string): Promise<any> {
    const token = getTerraformToken();
    const response = await fetch(`${TF_API_BASE}${endpoint}`, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/vnd.api+json'
      }
    });
  
    if (!response.ok) {
      throw new Error(`Terraform Cloud API error: ${response.statusText}`);
    }
  
    return response.json();
  }

• src/index.ts:14-22 (helper)

  Helper function to retrieve the Terraform Cloud API token from the credentials file, used by tfCloudRequest.

  function getTerraformToken(): string {
    const credentialsPath = join(homedir(), '.terraform.d', 'credentials.tfrc.json');
    try {
      const credentials = JSON.parse(readFileSync(credentialsPath, 'utf-8'));
      return credentials.credentials['app.terraform.io'].token;
    } catch (error) {
      throw new Error('Failed to read Terraform Cloud token from ~/.terraform.d/credentials.tfrc.json');
    }
  }