# infra-ops-mcp

The most comprehensive MCP (Model Context Protocol) server for infrastructure operations. **92 tools** across **13 categories** covering everything from local system monitoring to multi-cloud management.

[![npm version](https://img.shields.io/npm/v/infra-ops-mcp.svg)](https://www.npmjs.com/package/infra-ops-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)

## Features

- **92 Infrastructure Tools** organized in 13 categories
- **Cross-platform**: Windows (PowerShell), Linux, macOS
- **Multi-cloud**: AWS, Azure, GCP
- **Containers**: Docker + Kubernetes
- **Databases**: PostgreSQL, MySQL, MongoDB, Redis
- **CI/CD**: GitHub Actions, GitLab CI
- **IaC**: Terraform, Ansible, Pulumi
- **Security**: CVE scanning, secrets detection, TLS checks
- **Remote**: SSH fleet management with connection pooling
- **3-tier permission model**: SAFE, DANGEROUS, BLOCKED

## Quick Start

### Install

```bash
npm install -g infra-ops-mcp
```

### Configure with Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "infra-ops": {
      "command": "infra-ops-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_xxx",
        "INFRA_AWS_REGION": "us-east-1"
      }
    }
  }
}
```

### Run Standalone

```bash
# With default config
infra-ops-mcp

# With custom config
INFRA_CONFIG_PATH=./my-config.yaml infra-ops-mcp
```

### Development

```bash
git clone https://github.com/your-org/infra-ops-mcp.git
cd infra-ops-mcp
npm install
npm run build
npm run dev
```

## Tool Categories

### System (12 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `system_cpu_info` | SAFE | CPU cores, model, speed, load average |
| `system_memory_info` | SAFE | RAM usage, swap, top memory consumers |
| `system_disk_usage` | SAFE | Disk space by mount point, inodes |
| `system_process_list` | SAFE | Process list with filter and sort |
| `system_process_kill` | DANGEROUS | Kill process by PID |
| `system_service_list` | SAFE | System services status |
| `system_service_control` | DANGEROUS | Start/stop/restart services |
| `system_uptime` | SAFE | System uptime, last boot time |
| `system_users` | SAFE | User accounts, groups, logged in |
| `system_scheduled_tasks` | SAFE | Cron jobs / Task Scheduler |
| `system_hardware_info` | SAFE | BIOS, motherboard, PCI devices |
| `system_drivers` | SAFE | Loaded drivers / kernel modules |

### Network (9 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `network_interfaces` | SAFE | Adapters, IPs, MAC, speed |
| `network_routes` | SAFE | Routing table, default gateway |
| `network_dns_resolve` | SAFE | DNS lookup (A, AAAA, MX, CNAME, etc.) |
| `network_firewall_rules` | SAFE | Firewall rules list |
| `network_listening_ports` | SAFE | Open ports with associated process |
| `network_active_connections` | SAFE | Active TCP/UDP connections |
| `network_wifi_info` | SAFE | WiFi SSID, signal, channel |
| `network_bandwidth_test` | SAFE | Network throughput measurement |
| `network_traceroute` | SAFE | Hop-by-hop route trace |

### Storage (7 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `storage_raid_status` | SAFE | RAID array status |
| `storage_lvm_info` | SAFE | LVM volumes and groups |
| `storage_mounts` | SAFE | Mounted filesystems |
| `storage_smart_health` | SAFE | Disk SMART health data |
| `storage_partitions` | SAFE | Partition table info |
| `storage_nfs_shares` | SAFE | NFS exports and mounts |
| `storage_quotas` | SAFE | Disk quotas by user/group |

### Containers (18 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `docker_container_list` | SAFE | List containers |
| `docker_container_inspect` | SAFE | Container details |
| `docker_container_logs` | SAFE | Container logs |
| `docker_container_stats` | SAFE | Live container stats |
| `docker_container_start` | DANGEROUS | Start container |
| `docker_container_stop` | DANGEROUS | Stop container |
| `docker_container_restart` | DANGEROUS | Restart container |
| `docker_image_list` | SAFE | Local images |
| `docker_network_list` | SAFE | Docker networks |
| `docker_volume_list` | SAFE | Docker volumes |
| `docker_compose_status` | SAFE | Compose project status |
| `k8s_pod_list` | SAFE | Kubernetes pods |
| `k8s_pod_logs` | SAFE | Pod logs |
| `k8s_deployment_list` | SAFE | Deployments |
| `k8s_service_list` | SAFE | Services |
| `k8s_node_list` | SAFE | Cluster nodes |
| `k8s_events` | SAFE | Cluster events |
| `k8s_scale_deployment` | DANGEROUS | Scale replicas |

### Cloud (11 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `aws_ec2_instances` | SAFE | EC2 instances |
| `aws_s3_buckets` | SAFE | S3 buckets |
| `aws_rds_instances` | SAFE | RDS instances |
| `aws_lambda_functions` | SAFE | Lambda functions |
| `aws_cloudwatch_metrics` | SAFE | CloudWatch metrics |
| `aws_route53_zones` | SAFE | Route53 DNS zones |
| `azure_vm_list` | SAFE | Azure VMs |
| `azure_aks_clusters` | SAFE | AKS clusters |
| `azure_storage_accounts` | SAFE | Storage accounts |
| `gcp_compute_instances` | SAFE | GCE instances |
| `gcp_gke_clusters` | SAFE | GKE clusters |

### CI/CD (4 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `cicd_github_workflows` | SAFE | GitHub Actions workflows |
| `cicd_github_workflow_runs` | SAFE | Workflow run history |
| `cicd_gitlab_pipelines` | SAFE | GitLab pipelines |
| `cicd_gitlab_jobs` | SAFE | Pipeline jobs |

### Database (8 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `db_postgres_query` | SAFE | PostgreSQL read-only query |
| `db_postgres_health` | SAFE | PostgreSQL health check |
| `db_mysql_query` | SAFE | MySQL read-only query |
| `db_mysql_health` | SAFE | MySQL health check |
| `db_mongodb_query` | SAFE | MongoDB query |
| `db_mongodb_health` | SAFE | MongoDB health check |
| `db_redis_info` | SAFE | Redis INFO stats |
| `db_redis_health` | SAFE | Redis health check |

### IaC (5 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `iac_terraform_state` | SAFE | Terraform state |
| `iac_terraform_plan` | DANGEROUS | Run terraform plan |
| `iac_ansible_inventory` | SAFE | Ansible inventory |
| `iac_ansible_playbook_run` | DANGEROUS | Run playbook (--check) |
| `iac_pulumi_stacks` | SAFE | Pulumi stacks |

### Security (5 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `security_cve_scan` | SAFE | CVE vulnerability scan (Trivy) |
| `security_secrets_scan` | SAFE | Secrets detection (Gitleaks) |
| `security_cert_check` | SAFE | TLS certificate inspection |
| `security_compliance_check` | SAFE | CIS/STIG benchmarks |
| `security_port_audit` | SAFE | Open port security audit |

### Remote (3 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `remote_ssh_exec` | SAFE | Execute command via SSH |
| `remote_fleet_command` | DANGEROUS | Command across multiple hosts |
| `remote_host_inventory` | SAFE | Host inventory with status |

### DNS (3 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `dns_records` | SAFE | Query DNS records |
| `dns_propagation_check` | SAFE | Global DNS propagation |
| `dns_zone_query` | SAFE | Zone transfer query |

### Backup (3 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `backup_status` | SAFE | Backup status check |
| `backup_integrity_check` | SAFE | Verify backup integrity |
| `backup_restore_test` | DANGEROUS | Test restore to temp |

### Monitoring (4 tools)
| Tool | Tier | Description |
|------|------|-------------|
| `monitoring_custom_metrics` | SAFE | Query Prometheus metrics |
| `monitoring_uptime_check` | SAFE | HTTP/TCP uptime check |
| `monitoring_alerts` | SAFE | Active alerts |
| `monitoring_sla_status` | SAFE | SLA percentage calculator |

## Security Model

The 3-tier permission system protects against unintended operations:

| Tier | Behavior | Examples |
|------|----------|---------|
| **SAFE** | No confirmation needed | All list, info, health, read-only queries |
| **DANGEROUS** | Requires `confirm: true` | process_kill, service_control, docker start/stop, fleet_command, terraform_plan |
| **BLOCKED** | Disabled by default | DB writes, delete operations (enable in config) |

### Example: Dangerous Operation

```json
{
  "name": "system_process_kill",
  "arguments": {
    "pid": 1234,
    "confirm": true
  }
}
```

Without `confirm: true`, dangerous tools return an error message explaining the requirement.

## Configuration

### Config File (`config/default.yaml`)

The server loads configuration from:
1. `./config/default.yaml` (project directory)
2. `~/.infra-ops-mcp/config.yaml` (user home)
3. Environment variables (highest priority)

### Environment Variables

| Variable | Description |
|----------|-------------|
| `GITHUB_TOKEN` | GitHub personal access token |
| `GITLAB_TOKEN` | GitLab access token |
| `INFRA_AWS_REGION` | AWS region |
| `INFRA_AWS_PROFILE` | AWS profile name |
| `INFRA_GCP_PROJECT` | GCP project ID |
| `INFRA_AZURE_SUBSCRIPTION` | Azure subscription ID |
| `INFRA_PG_HOST` | PostgreSQL host |
| `INFRA_PG_PORT` | PostgreSQL port |
| `INFRA_PG_USER` | PostgreSQL user |
| `INFRA_PG_PASSWORD` | PostgreSQL password |
| `INFRA_PG_DATABASE` | PostgreSQL database |
| `INFRA_REDIS_HOST` | Redis host |
| `INFRA_REDIS_PORT` | Redis port |
| `INFRA_REDIS_PASSWORD` | Redis password |

### Host Inventory (`config/hosts.yaml`)

Ansible-style host definitions for remote operations:

```yaml
hosts:
  - host: web-01.example.com
    user: deploy
    port: 22
    privateKey: ~/.ssh/web_servers
    groups:
      - webservers
      - production
    labels:
      environment: production
      role: web
```

## Architecture

```
src/
├── index.ts           # Entry point
├── server.ts          # MCP Server + StdioTransport
├── registry.ts        # ToolRegistry with permission guards
├── core/              # Platform detection, executor, permissions, errors
├── infra/             # SSH pool, circuit breaker, cache, rate limiter
├── config/            # YAML config loader, env overrides
├── tools/             # 13 tool modules (76 tools total)
└── utils/             # Parsers, formatters
```

## Requirements

- **Node.js** >= 18.0.0
- **Optional**: Docker, kubectl, AWS CLI, Azure CLI, gcloud, Terraform, Ansible, Trivy, Gitleaks

Tools gracefully handle missing dependencies - if Docker isn't installed, Docker tools will return appropriate error messages rather than crashing.

## License

MIT