mcp-sysoperator

The MCP SysOperator server exposes a set of infrastructure automation tools that let an AI assistant interact with Ansible and Terraform from within the MCP framework. It provides capabilities to run Ansible playbooks, list and inspect inventories, check syntax, and preview tasks. It also integrates with AWS operations, Terraform workflows (init, plan, apply, destroy, and output), and LocalStack for local cloud testing. Use the provided MCP tool invocations to send requests to the sysoperator server, specifying the appropriate action (e.g., run_playbook, list_inventory, check_syntax, list_tasks, aws_s3, terraform) and a structured arguments payload. The server is designed to work with both real cloud environments and local test environments via LocalStack, enabling safer development and validation of infrastructure code.

Typical workflows include: running a playbook with inventory and extraVars to configure deployments, validating playbooks before execution, previewing tasks in a playbook to understand what will run, and managing Terraform projects through init/plan/apply cycles. For AWS interactions, you can list or manage resources such as S3 buckets or other services, and you can use Terraform with LocalStack for local testing before deploying to real AWS environments. The LocalStack integration also enables end-to-end validation of AWS-related Ansible and Terraform code without requiring AWS credentials.

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Ansible installed and in PATH
• Access to an MCP-enabled environment (as per your MCP settings)
• @modelcontextprotocol/sdk installed (automatically as a dependency)
• For AWS operations: AWS CLI and valid credentials (or use LocalStack for local testing)
• For LocalStack: LocalStack installed and running, awslocal CLI

Install and build

1. Clone the repository

git clone https://github.com/tarnover/mcp-sysoperator.git
cd mcp-sysoperator

2. Install dependencies

npm install

3. Build the server

npm run build

4. Configure MCP settings Add the sysoperator MCP server to your MCP configuration. Create or edit your MCP settings file (examples shown). Replace "/absolute/path/to/mcp-sysoperator" with the actual installation path.

VSCode Claude extension (settings file example):

{
  "mcpServers": {
    "sysoperator": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-sysoperator/build/index.js"],
      "env": {}
    }
  }
}

Claude Desktop / Claude CLI example (settings file):

# Add the above JSON under the mcpServers section

Tips and common notes:

• Ensure Node.js 18+ is in your PATH and that npm install completes without errors before running the build.
• The server is started by invoking node build/index.js through the MCP configuration; ensure the path is absolute.
• For AWS-related work, either provide real AWS credentials or use LocalStack with the LocalStack integration included in the repository.
• If you modify playbooks or inventory paths, ensure those files are accessible from the environment where the MCP server runs.
• When using Terraform with LocalStack (tflocal), set useLocalstack to true and provide the appropriate workingDir and vars as needed.
• Check that Ansible is installed and available in the system PATH on the host running the MCP server.
• If you encounter permission issues, verify file permissions for the mounted volumes or the working directories used by the MCP server.