controlmonkey-mcp 1.0.0

MCP server for ControlMonkey — AI-assisted infrastructure management

ControlMonkey MCP Server

Manage your cloud infrastructure through natural language. The ControlMonkey MCP server connects AI assistants like Cursor, Claude Code, and Windsurf directly to your ControlMonkey platform - so you can query, create, and operate your Terraform workflows without leaving your editor.

Example Use Cases

Investigate a Failed Deployment

When a deployment fails, ask the AI to pull the logs and diagnose the issue directly in your IDE.

The last deployment on stack "payments-service" failed.
Get the deployment details and show me the Terraform apply logs.
What went wrong?

Policy and Compliance Setup

Enforce governance rules across your infrastructure using control policies.

Create a control policy that prevents deploying resources without
the "team" and "environment" tags. Map it to the "production"
namespace so it applies to all stacks there.

Available Tools

The available tools of the agents are built dynamically during the MCP server startup based on the API token's role and permissions. Once connected, your AI assistant can help you:

• Namespaces & Stacks — Create, update, query, and delete namespaces and Terraform stacks
• Plans & Deployments — Trigger Terraform plans and deployments, review states, approve or cancel runs
• Templates — Manage ephemeral and persistent templates, create stacks from templates
• Variables — Create and manage Terraform input variables across scopes
• Control Policies — Create policies and policy groups, map them to targets for governance
• Cloud Credentials — Manage AWS, Azure, and GCP credentials
• Notifications — Configure Slack, Teams, and email notification endpoints and subscriptions
• Disaster Recovery — Set up and manage DR configurations
• Auto Discovery — Configure automatic stack discovery for namespaces
• VCS & SSH Keys — Add version control providers and manage SSH keys
• Audit — Query audit events across your organization

⚠️ Note – Use AI With Caution

ControlMonkey integrates with third-party LLM providers but does not control the underlying models or their outputs. AI-generated suggestions - including code changes, remediation steps, and infrastructure modifications - should always be reviewed by a qualified team member before being applied to your environment.

Prerequisites

1. Install uv

This server uses uv, the standard Python package manager for the MCP ecosystem.

macOS:

brew install uv

Linux / WSL:

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

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Create a Programmatic User

You'll need an API token from a ControlMonkey Programmatic User. Follow the Programmatic Users guide to create one.

Note: The role you assign determines which operations are available through the MCP server. Choose permissions appropriate for your use case.

Quick Start

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "controlmonkey": {
      "command": "uvx",
      "args": ["controlmonkey-mcp"],
      "env": {
        "CM_BASE_URL": "https://api.controlmonkey.io",
        "CM_API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Code

Run in your terminal:

claude mcp add-json controlmonkey '{"command":"uvx","args":["controlmonkey-mcp"],"env":{"CM_BASE_URL":"https://api.controlmonkey.io","CM_API_TOKEN":"your-api-token"}}'

To make it available across all projects, add the --scope user flag:

claude mcp add-json controlmonkey --scope user '{"command":"uvx","args":["controlmonkey-mcp"],"env":{"CM_BASE_URL":"https://api.controlmonkey.io","CM_API_TOKEN":"your-api-token"}}'

Verify it's connected:

claude mcp list

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "controlmonkey": {
      "command": "uvx",
      "args": ["controlmonkey-mcp"],
      "env": {
        "CM_BASE_URL": "https://api.controlmonkey.io",
        "CM_API_TOKEN": "your-api-token"
      }
    }
  }
}

After saving, click Refresh in the MCP toolbar to connect.

Run Directly

CM_BASE_URL=https://api.controlmonkey.io CM_API_TOKEN=your-api-token uvx controlmonkey-mcp

Configuration

You can set configuration via environment variables or a .env file:

Variable	Required	Default	Description
CM_BASE_URL	✅	—	ControlMonkey API base URL
CM_API_TOKEN	✅	—	Your Programmatic User API token
CM_REQUEST_TIMEOUT		30	HTTP timeout in seconds

Troubleshooting

externally-managed-environment error — Install uv (see Prerequisites) and use uvx instead of running with system Python.

Tools not appearing or outdated — uvx caches packages. Run uv cache clean and restart your MCP client.

Acknowledgments

Special thanks to Lior Azroel (@liorazroel) for helping shape the use cases behind this project.

Resources

• ControlMonkey Website
• Documentation
• API Reference
• Programmatic Users Guide