Terraform Cloud MCP Server

Instructions

Implementation Reference

• src/index.ts:70-115 (handler)

  The handler function that implements the logic for the 'get_run_status' tool, fetching workspace details, current run status, and recent runs from the Terraform Cloud API.

  async ({ workspaceName, organization }) => {
    try {
      // Get workspace details
      const workspaceData = await tfCloudRequest(`/organizations/${organization}/workspaces/${workspaceName}`);
      const workspaceId = workspaceData.data.id;
      
      // Get current run if exists
      const currentRunData = workspaceData.data.relationships['current-run']?.data;
      let currentRunId: string | undefined;
      let currentRunStatus: string | undefined;
  
      if (currentRunData?.id) {
        currentRunId = currentRunData.id;
        const runData = await tfCloudRequest(`/runs/${currentRunId}`);
        currentRunStatus = runData.data.attributes.status;
      }
  
      // Get recent runs
      const runsData = await tfCloudRequest(`/workspaces/${workspaceId}/runs?page[size]=5`);
      const recentRuns = runsData.data.map((run: any) => ({
        id: run.id,
        status: run.attributes.status,
        createdAt: run.attributes['created-at'],
        message: run.attributes.message || 'No message'
      }));
  
      const output = {
        workspaceId,
        workspaceName,
        currentRunId,
        currentRunStatus,
        recentRuns
      };
  
      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:51-69 (schema)

  Input and output schema definitions, including Zod validators, for the 'get_run_status' tool.

    title: 'Get Run Status',
    description: 'Get the current run status for a Terraform Cloud workspace',
    inputSchema: {
      workspaceName: z.string().describe('Workspace name'),
      organization: z.string().default('urbanmedia').describe('Organization name')
    },
    outputSchema: {
      workspaceId: z.string(),
      workspaceName: z.string(),
      currentRunId: z.string().optional(),
      currentRunStatus: z.string().optional(),
      recentRuns: z.array(z.object({
        id: z.string(),
        status: z.string(),
        createdAt: z.string(),
        message: z.string()
      }))
    }
  },

• src/index.ts:48-116 (registration)

  Registration of the 'get_run_status' tool using server.registerTool, including name, schema, and handler function.

  server.registerTool(
    'get_run_status',
    {
      title: 'Get Run Status',
      description: 'Get the current run status for a Terraform Cloud workspace',
      inputSchema: {
        workspaceName: z.string().describe('Workspace name'),
        organization: z.string().default('urbanmedia').describe('Organization name')
      },
      outputSchema: {
        workspaceId: z.string(),
        workspaceName: z.string(),
        currentRunId: z.string().optional(),
        currentRunStatus: z.string().optional(),
        recentRuns: z.array(z.object({
          id: z.string(),
          status: z.string(),
          createdAt: z.string(),
          message: z.string()
        }))
      }
    },
    async ({ workspaceName, organization }) => {
      try {
        // Get workspace details
        const workspaceData = await tfCloudRequest(`/organizations/${organization}/workspaces/${workspaceName}`);
        const workspaceId = workspaceData.data.id;
        
        // Get current run if exists
        const currentRunData = workspaceData.data.relationships['current-run']?.data;
        let currentRunId: string | undefined;
        let currentRunStatus: string | undefined;
  
        if (currentRunData?.id) {
          currentRunId = currentRunData.id;
          const runData = await tfCloudRequest(`/runs/${currentRunId}`);
          currentRunStatus = runData.data.attributes.status;
        }
  
        // Get recent runs
        const runsData = await tfCloudRequest(`/workspaces/${workspaceId}/runs?page[size]=5`);
        const recentRuns = runsData.data.map((run: any) => ({
          id: run.id,
          status: run.attributes.status,
          createdAt: run.attributes['created-at'],
          message: run.attributes.message || 'No message'
        }));
  
        const output = {
          workspaceId,
          workspaceName,
          currentRunId,
          currentRunStatus,
          recentRuns
        };
  
        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 API requests to Terraform Cloud, heavily used in the tool 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 user's 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');
    }
  }