Terraform IBM Modules MCP

A Model Context Protocol (MCP) server that provides structured access to the Terraform IBM Modules (TIM) ecosystem. TIM is a curated collection of IBM Cloud Terraform modules designed to follow best practices.

Overview

The TIM-MCP server acts as a bridge between AI models and the Terraform IBM Modules ecosystem, enabling intelligent discovery and utilization of IBM Cloud infrastructure resources.

Key Features

Module Search: Find relevant modules in the Terraform Registry with quality-based ranking
Module Details: Get structured information about inputs, outputs, and dependencies
Repository Exploration: Navigate examples, submodules, and implementation patterns
Content Retrieval: Access documentation, example code, and other repository files
White Paper Resource: Access the IBM Cloud Terraform Best Practices white paper
AI-Assisted Workflows: Tools designed to support infrastructure code generation

Important Notes

⚠️ Experimental Status: This MCP server and the solutions it helps generate are experimental. Generated configurations should always be reviewed by skilled practitioners before use in any environment.

⚠️ Human Review Required: Even when the tools and workflows mature, human expertise will remain essential for reviewing outputs, making final adjustments, and ensuring configurations meet specific requirements.

Why TIM-MCP?

TIM-MCP guides foundation models (FMs) to produce better IBM Cloud infrastructure solutions by:

Steering models toward best practices

Without TIM-MCP, foundation models might generate generic or outdated Terraform code. TIM-MCP steers models toward IBM-validated patterns and current best practices by providing direct access to curated modules, preventing common anti-patterns and ensuring alignment with IBM Cloud architecture recommendations.

Providing contextual guardrails

TIM-MCP acts as a guardrail system, helping models navigate the complex IBM Cloud ecosystem. It provides structured access to module interfaces, dependencies, and implementation patterns, reducing the likelihood of hallucinated parameters or incompatible resource combinations.

Enhancing precision with real-time module data

Foundation models may have limited or outdated knowledge of IBM Cloud Terraform modules. TIM-MCP provides real-time access to module details, ensuring AI assistants generate code with accurate input variables, correct resource configurations, and proper module versioning.

Unlocking distributed knowledge

By connecting models to documentation and examples spread across many repositories, TIM-MCP helps foundation models leverage the collective expertise embedded in the TIM ecosystem, resulting in more accurate and production-ready infrastructure code.

Prerequisites

Before configuring TIM-MCP, ensure you have the following installed:

uv Package Manager (required for running the MCP server)

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

winget install --id=astral-sh.uv -e

Verify installation:

uv --version

GitHub Personal Access Token (optional but recommended)

A GitHub token helps avoid API rate limits when accessing TIM repositories:
- Without token: 60 requests/hour
- With token: 5,000 requests/hour
To create a token:
- Go to: GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
- Create a token with:
  - Repository access: "Public repositories only"
  - Permissions: No private access scopes needed
  - Expiration: Set to 90 days or longer

Installation Instructions

Claude Desktop

Claude Desktop is a standalone application that supports MCP servers through a JSON configuration file.

Install uv (if not already installed) - see Prerequisites section

Add TIM-MCP Configuration:

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

Basic Configuration:

{
  "mcpServers": {
    "tim-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/terraform-ibm-modules/tim-mcp.git",
        "tim-mcp"
      ]
    }
  }
}

With GitHub Token (recommended to avoid rate limits):

{
  "mcpServers": {
    "tim-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/terraform-ibm-modules/tim-mcp.git",
        "tim-mcp"
      ],
      "env": { "GITHUB_TOKEN": "your_github_token_here" }
    }
  }
}

Restart Claude Desktop and look for the 🔨 icon to confirm MCP tools are loaded
Test it: Ask Claude "What IBM Cloud VPC modules are available?"

VS Code

Visual Studio Code supports MCP servers through extension and configuration files.

Install the MCP extension for VS Code if not already installed
Configure TIM-MCP using one of these methods:
- Create/edit .vscode/mcp.json in your project directory
- Use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and select "MCP: Add Server"
Add the configuration using the same JSON format as shown in the Claude Desktop section

Cursor

Cursor IDE supports MCP servers through configuration files.

Create/edit one of these files:
- .cursor/mcp.json in your project directory
- ~/.cursor/mcp.json for global configuration
Add the configuration using the same JSON format as shown in the Claude Desktop section

IBM Bob

IBM Bob supports MCP servers through configuration files.

Configuring MCP Servers in Bob

MCP server configurations can be managed at two levels:

Project-level Configuration: Create the file .bob/mcp.json within your project directory, and then add the configuration using the JSON format shown in the Claude Desktop section
Global Configuration: Stored in the mcp_settings.json file, accessible via VS Code settings. These settings apply across all your workspaces unless overridden by a project-level configuration.
1. Click the icon in the top navigation of the Bob pane.
2. Scroll to the bottom of the MCP settings view.
3. Click Edit Global MCP: Opens the global mcp_settings.json file.
4. Add the configuration using the same JSON format as shown in the Claude Desktop section

Claude Code

Claude Code supports configuration via CLI or config file. The configuration format is similar to the Claude Desktop section.

CLI Method:

# Navigate to your project directory first
cd /path/to/your/project

# Add the MCP server with GitHub token
claude mcp add tim-mcp --env GITHUB_TOKEN=your_github_token_here \
  -- uvx --from git+https://github.com/terraform-ibm-modules/tim-mcp.git tim-mcp

# Or without GitHub token (may hit rate limits)
claude mcp add tim-mcp -- uvx --from git+https://github.com/terraform-ibm-modules/tim-mcp.git tim-mcp

# List configured MCP servers
claude mcp list

# Remove if needed
claude mcp remove tim-mcp

Version Pinning

For production use, pin to a specific version to ensure consistent behavior (using the same format as in the Claude Desktop section):

{
  "mcpServers": {
    "tim-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/terraform-ibm-modules/[email protected]",
        "tim-mcp"
      ],
      "env": { "GITHUB_TOKEN": "your_github_token_here" }
    }
  }
}

Note: Check the releases page for the latest version tag.

Verification

After configuration:

Restart your IDE or Claude Desktop completely
Check for the hammer icon (🔨) in the input box, indicating MCP tools are available
Test by asking: "What IBM Cloud Terraform modules are available for VPC?"

Troubleshooting

Common Issues and Solutions

Server not starting:

Ensure uv is installed and available in your PATH
Verify your MCP configuration JSON syntax is valid

No tools appearing:

Restart your IDE or Claude Desktop completely
Check logs for error messages

Rate limiting errors:

Add a GITHUB_TOKEN environment variable with a valid GitHub personal access token
The token needs only public repository access permissions

Token Authentication Fails:

Verify token is valid and not expired
Check token has public repository access
Ensure token is in quotes in JSON
Test token manually:

curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

Using TIM-MCP

Once configured, your AI assistant can help you build IBM Cloud infrastructure from simple to complex deployments. Ask for help with scenarios like:

Getting Started with IBM Cloud

"I am new to IBM Cloud. Help me create a simple and cheap OpenShift cluster and access the console"
"I want to create a simple basic virtual server on IBM Cloud and SSH to it"

Building Enterprise Infrastructure

"Design a VPC + OpenShift: Create a complete container platform with networking, including multi-zone VPC, subnets, OpenShift/ROKS cluster, and load balancers"
"Design a Secure Landing Zone: Implement enterprise-grade security with network isolation, encryption key management, private endpoints, and security groups"
"Design a Multi-Zone HA Database: Design resilient database infrastructure across 3+ availability zones with automated failover, backup strategies, and disaster recovery"

Quick Solutions

"Design a Quick POC Setup: Rapidly deploy a minimal viable environment with compute instances, basic networking, and essential services for testing"
"Design a FS-Validated Architecture: Deploy compliant infrastructure meeting Financial Services requirements with HPCS encryption, audit logging, and regulatory controls"
"Design a Hub-Spoke Network: Create an enterprise network architecture with centralized connectivity, network segmentation, and secure VPC interconnection"

Additional Resources

TIM-MCP Repository: https://github.com/terraform-ibm-modules/tim-mcp
Model Context Protocol Docs: https://modelcontextprotocol.io
GitHub API Rate Limit Docs: https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api
Terraform Registry (IBM Modules): https://registry.terraform.io/namespaces/terraform-ibm-modules

For Developers

If you're interested in contributing to TIM-MCP or modifying the server itself, please see the Development Guide for detailed instructions on development setup, transport modes, and advanced configuration options.

Contributing

You can report issues and request features for this module in GitHub issues in the module repo. See Report an issue or request a feature.

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github		.github
common-dev-assets @ 1df43f2		common-dev-assets @ 1df43f2
examples		examples
scripts		scripts
static		static
test		test
tim_mcp		tim_mcp
.gitignore		.gitignore
.gitmodules		.gitmodules
.pre-commit-config.yaml		.pre-commit-config.yaml
.releaserc		.releaserc
.secrets.baseline		.secrets.baseline
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
ci		ci
pyproject.toml		pyproject.toml
renovate.json		renovate.json
uv.lock		uv.lock

License

terraform-ibm-modules/tim-mcp

Folders and files

Latest commit

History

Repository files navigation

Terraform IBM Modules MCP

Table of Contents

Overview

Key Features

Important Notes

Why TIM-MCP?

Steering models toward best practices

Providing contextual guardrails

Enhancing precision with real-time module data

Unlocking distributed knowledge

Prerequisites

Installation Instructions

Claude Desktop

VS Code

Cursor

IBM Bob

Configuring MCP Servers in Bob

Claude Code

Version Pinning

Verification

Troubleshooting

Common Issues and Solutions

Using TIM-MCP

Getting Started with IBM Cloud

Building Enterprise Infrastructure

Quick Solutions

Additional Resources

For Developers

Contributing

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 20

Packages 0

Contributors 4

Uh oh!

Languages

Packages