Terraform MCP Server

A comprehensive Model Context Protocol (MCP) server for Terraform operations, featuring secure command execution, semantic document search, and intelligent document ingestion with vector embeddings and Neo4j integration.

---

✨ Key Features

🔒 Secure Terraform Execution

• Execute Terraform commands with comprehensive validation and security checks
• Command whitelisting (init, plan, validate, apply, destroy)
• Directory traversal protection and dangerous pattern detection
• Configurable timeouts (1-1800 seconds)
• 100+ dangerous patterns detected

🔍 Semantic Document Search

• Vector similarity search over Terraform documentation
• HNSW-based similarity search with cosine scoring
• 1536-dimensional embeddings with configurable thresholds
• Search across resources, data sources, and best practices
• 10-100ms query times

📚 Intelligent Document Ingestion

• Process Terraform resources, data sources, and best practices
• Multi-format support: HTML, Markdown, PDF
• LLM-powered content extraction and structuring
• Semantic chunking with metadata preservation
• Incremental processing with Neo4j storage

🤖 Multi-Provider AI Support

• OpenAI, Anthropic, Azure OpenAI
• HuggingFace, Cohere, Ollama
• Configurable embedding models
• LLM-powered content extraction

---

🏗️ Architecture

---

📦 Quick Start

Prerequisites

Requirement	Description
Python 3.12+	Required for installation
Neo4j 4.4+	With vector search support
Terraform CLI	For command execution
AI Provider API Key	OpenAI, Anthropic, or others

Quick Installation

# Clone the repository
git clone git@github.com:talkops-ai/talkops-mcp.git
cd talkops-mcp/src/terraform-mcp-server

# Create virtual environment
uv venv --python=3.12
source .venv/bin/activate

# Install dependencies
uv pip install -e .

# Start the server
uv run terraform_mcp_server

Connect Your MCP Client

{
  "mcpServers": {
    "terraform-mcp-server": {
      "transport": "sse",
      "url": "http://localhost:8000/sse",
      "description": "Terraform MCP Server for IaC operations"
    }
  }
}

---

🛠️ Core Tools

The server provides three MCP tools:

Tool	Description
terraform_execute	Secure execution of Terraform commands with validation
terraform_doc_search	Semantic similarity search over Terraform documentation
ingest_terraform_docs	Document ingestion with vector embeddings

---

🔒 Security Features

Feature	Description
Command Whitelisting	Only allowed Terraform commands can be executed
Directory Validation	Working directory validation with traversal protection
Pattern Detection	Dangerous pattern detection in variables and commands
Timeout Limits	Configurable execution timeouts (max 30 minutes)
Output Sanitization	ANSI code removal and output length limiting
Variable Security	Maximum 100 variables, pattern scanning

---

📁 Project Structure

terraform-mcp-server/
├── terraform_mcp_server/      # Main package
│   ├── tools/                 # MCP Tools
│   │   ├── tf_execution/      # Terraform command execution
│   │   ├── tf_search/         # Document search
│   │   └── tf_ingestion/      # Document ingestion
│   ├── services/              # Business logic
│   │   ├── embedding/         # Vector embeddings
│   │   ├── llm/               # LLM integration
│   │   └── neo4j/             # Graph database
│   ├── server/                # FastMCP server setup
│   └── config.py              # Configuration management
├── tests/                     # Test suite
└── pyproject.toml             # Project configuration

---

🙏 Acknowledgments

• AWS Labs: For foundational inspiration from their Terraform MCP server
• HashiCorp: For excellent Terraform documentation
• Neo4j: For powerful graph database and vector search
• LangChain: For comprehensive AI framework integration
• Model Context Protocol: For the MCP specification

---

Next Steps

• ⚙️ Configuration - Complete setup and environment variables
• 🛠️ Tools - Available MCP tools reference
• 📖 Examples - Usage patterns and workflows