controlmonkey-mcp 1.0.0
MCP server for ControlMonkey — AI-assisted infrastructure management
Requires Python: >=3.11
Keywords: ai, automation, aws, azure, cloud, controlmonkey, devops, gcp, iac, infrastructure-as-code, mcp, model-context-protocol, terraform

# 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](https://controlmonkey.io/) 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`](https://docs.astral.sh/uv/), the standard Python package manager for the MCP ecosystem.

**macOS:**
```bash
brew install uv
```

**Linux / WSL:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows:**
```bash
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](https://docs.controlmonkey.io/administration/users-and-roles/programmatic-users) 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`:

```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:

```bash
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:

```bash
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:

```bash
claude mcp list
```

### Windsurf

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

```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

```bash
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)](https://github.com/liorazroel) for helping shape the use cases behind this project.

## Resources

- [ControlMonkey Website](https://controlmonkey.io/)
- [Documentation](https://docs.controlmonkey.io/)
- [API Reference](https://docs.controlmonkey.io/controlmonkey-api/)
- [Programmatic Users Guide](https://docs.controlmonkey.io/administration/users-and-roles/programmatic-users)