mcp-tfstate-reader

License: MIT

A local Model Context Protocol (MCP) server that parses Terraform .tfstate files and lets AI agents audit enterprise infrastructure for security misconfigurations — without requiring direct cloud credentials.

Why?

Terraform state files are the single source of truth for what's actually deployed in your cloud. Security teams need to audit them regularly, but the traditional workflow is manual: run CLI tools, parse terminal output, repeat.

mcp-tfstate-reader gives AI agents (like Claude) structured, read-only access to your Terraform state. Instead of copying JSON into a chat window, you ask a question and the agent calls the right tool automatically.

Features

Tool	Description
`list_resources`	Parse a `.tfstate` file and list every managed resource with its address and type
`audit_security`	Scan for common misconfigurations (see below)
`get_resource_detail`	Dump the full attributes of a specific resource by address
`summarize_state`	High-level overview: resource counts by type/module, providers, tags, regions
`compare_states`	Infrastructure drift detection — diff two state files for added/removed/modified

Security checks in `audit_security`

S3 — buckets without server-side encryption; buckets without versioning enabled
S3 ACL — bucket ACLs set to public-read or public-read-write
Security Groups — ingress rules open to 0.0.0.0/0 on sensitive ports: 22 (SSH), 3389 (RDP), 5432 (PostgreSQL)
IAM — policies with wildcard * actions (full admin access)
RDS — instances without storage_encrypted = true; publicly accessible instances
EBS — volumes without encryption
EC2 — instances with associate_public_ip_address = true
Lambda — functions not deployed in a VPC
KMS — keys without automatic key rotation enabled
ElastiCache — replication groups without transit encryption
SNS — topics without KMS encryption
SQS — queues without KMS encryption
ALB/NLB — load balancers without access logs enabled
CloudWatch — log groups without a retention policy

Quick Start

1. Install

pip install mcp-tfstate-reader

2. Configure Claude Desktop

Add this to your Claude Desktop MCP configuration file:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Recommended — with uvx (no install required):

{
  "mcpServers": {
    "tfstate-reader": {
      "command": "uvx",
      "args": ["mcp-tfstate-reader"]
    }
  }
}

Note: Claude Desktop may not inherit your terminal's $PATH. If the server fails to connect, use the absolute path to uvx (find it with which uvx in your terminal):
{
  "mcpServers": {
    "tfstate-reader": {
      "command": "/full/path/to/uvx",
      "args": ["mcp-tfstate-reader"]
    }
  }
}

Alternative — installed via pip:

{
  "mcpServers": {
    "tfstate-reader": {
      "command": "mcp-tfstate-reader"
    }
  }
}

Alternative — from source (virtualenv):

{
  "mcpServers": {
    "tfstate-reader": {
      "command": "/absolute/path/to/mcp-tfstate-reader/.venv/bin/python",
      "args": ["-m", "mcp_tfstate_reader.server"]
    }
  }
}

3. Restart Claude Desktop

Fully quit (Cmd+Q on macOS) and reopen. Look for the tools icon to confirm the server is connected.

4. Ask a question

"Audit the Terraform state file at /path/to/terraform.tfstate for security issues."

Example interaction

Claude autonomously chains the tools — listing resources first, running the audit, then drilling into critical findings:

Found 17 finding(s):

[CRITICAL] aws_iam_policy.admin: IAM policy contains a wildcard (*) action — grants unrestricted permissions.
[HIGH] aws_s3_bucket.assets: S3 bucket has no server-side encryption configuration.
[HIGH] aws_s3_bucket_acl.assets: S3 bucket ACL is set to 'public-read' — allows public access.
[HIGH] aws_security_group.bastion: Security group allows 0.0.0.0/0 ingress on port 22.
[HIGH] aws_security_group.rdp_open: Security group allows 0.0.0.0/0 ingress on port 3389.
[HIGH] aws_db_instance.prod: RDS instance storage is not encrypted.
[HIGH] aws_db_instance.prod: RDS instance is publicly accessible.
[HIGH] aws_ebs_volume.data: EBS volume is not encrypted.
[HIGH] aws_elasticache_replication_group.sessions: ElastiCache replication group does not have transit encryption enabled.
[MEDIUM] aws_s3_bucket.assets: S3 bucket does not have versioning enabled.
[MEDIUM] aws_instance.web: EC2 instance has a public IP address assigned.
[MEDIUM] aws_lambda_function.processor: Lambda function is not deployed in a VPC.
[MEDIUM] aws_kms_key.app: KMS key does not have automatic key rotation enabled.
[MEDIUM] aws_sns_topic.alerts: SNS topic is not encrypted with a KMS key.
[MEDIUM] aws_sqs_queue.jobs: SQS queue is not encrypted with a KMS key.
[MEDIUM] aws_lb.frontend: Load balancer does not have access logs enabled.
[MEDIUM] aws_cloudwatch_log_group.app: CloudWatch log group has no retention policy (logs kept indefinitely).

Troubleshooting

Server not appearing in Claude Desktop

Ensure Claude Desktop is fully restarted (quit with Cmd+Q, not just close the window).
Check your config JSON is valid — a trailing comma or typo will silently break it.
Use absolute paths if uvx or mcp-tfstate-reader aren't found.

"File not found" errors

The tool reads files from your local filesystem. Use the full absolute path (e.g. /Users/you/infra/terraform.tfstate), not relative paths.

This is Claude Desktop only

MCP servers work with the Claude Desktop app, not claude.ai in your browser. The web interface does not have access to local MCP servers or your filesystem.

Development

# Clone and set up
git clone https://github.com/berkayildi/mcp-tfstate-reader.git
cd mcp-tfstate-reader
make setup

# Run tests
make test

# Build distribution
make build

# Run the server locally (stdio)
make start

# Clean everything
make clean

mcp-tfstate-reader