Civo MCP Server

An MCP server implementation that integrates with the Civo cloud platform API, providing capabilities to manage cloud instances, networks, and Kubernetes clusters.

Demo

Or you can also view the details of each step through this public Amp thread.

Getting Started

Requirements

• Node.js 20 or newer
• Claude Desktop, VS Code, Cursor, or any other MCP client
• A Civo account with API key

Installation

First, install the Civo MCP server with your client. A typical configuration looks like this:

{
  "mcpServers": {
    "civo": {
      "command": "npx",
      "args": ["civo-mcp"],
      "env": {
        "CIVO_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Install in VS Code

You can install the Civo MCP server using the VS Code CLI:

# For VS Code
code --add-mcp '{"name":"civo","command":"npx","args":["civo-mcp"],"env":{"CIVO_API_KEY":"YOUR_API_KEY_HERE"}}'

After installation, the Civo MCP server will be available for use with your GitHub Copilot agent in VS Code.

Install in Ampcode

Follow Amp MCP documentation. Use following configuration:

"amp.mcpServers": {
  "civo": {
      "command": "npx",
      "args": ["civo-mcp"],
      "env": {
        "CIVO_API_KEY": "YOUR_API_KEY_HERE"
      }
  }
}

Install in Claude Code

Use the Claude Code CLI to add the Civo MCP server:

claude mcp add civo npx civo-mcp

Then set your API key as an environment variable:

export CIVO_API_KEY="your_api_key_here"

Install in Gemini CLI

Follow the MCP install guide, use following configuration:

{
  "mcpServers": {
    "civo": {
      "command": "npx",
      "args": ["civo-mcp"],
      "env": {
        "CIVO_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Install in Cursor

Go to `Cursor Settings` → `MCP` → `Add new MCP Server`. Name to your liking, use `command` type with the command `npx civo-mcp`. You can also verify config or add command like arguments via clicking `Edit`.

{
  "mcpServers": {
    "civo": {
      "command": "npx",
      "args": ["civo-mcp"],
      "env": {
        "CIVO_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Install in Windsurf

Follow Windsurf MCP documentation. Use following configuration:

{
  "mcpServers": {
    "civo": {
      "command": "npx",
      "args": ["civo-mcp"],
      "env": {
        "CIVO_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Install in Claude Desktop

Follow the MCP install guide, use following configuration:

{
  "mcpServers": {
    "civo": {
      "command": "npx",
      "args": ["civo-mcp"],
      "env": {
        "CIVO_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Features

• Instance Management: Create, manage, resize, start, stop, reboot, and delete cloud instances.
• Disk Image Operations: List and get details of available disk images.
• Network Management: Create, rename, and delete networks.
• Kubernetes Support: Create, list, and delete Kubernetes clusters and list available versions.
• Flexible Configuration: Set instance size, region, and other parameters.
• Rate Limiting: Built-in rate limiting to prevent API abuse.

Tools

Instance Management

• create_instance
  • Create new cloud instances on Civo
  • Inputs:
    • `hostname` (string): Fully qualified domain name
    • `size` (string): Instance size (e.g. 'g2.small')
    • `template_id` (string): Disk image ID
    • `count` (number, optional): Number of instances to create (default: 1)
    • `region` (string, optional): Region identifier (default: 'LON1')

• list_instances
  • List all instances on Civo
  • Inputs:
    • `region` (string, optional): Filter by region
    • `page` (number, optional): Pagination page (default: 1)
    • `per_page` (number, optional): Results per page (default: 20)

• reboot_instance
  • Reboot an existing instance
  • Inputs:
    • `id` (string): Instance ID
    • `region` (string): Region identifier

• shutdown_instance
  • Shutdown an existing instance
  • Inputs:
    • `id` (string): Instance ID
    • `region` (string): Region identifier

• start_instance
  • Start a stopped instance
  • Inputs:
    • `id` (string): Instance ID
    • `region` (string): Region identifier

• resize_instance
  • Resize an existing instance
  • Inputs:
    • `id` (string): Instance ID
    • `size` (string): New instance size
    • `region` (string): Region identifier

• delete_instance
  • Delete an existing instance
  • Inputs:
    • `id` (string): Instance ID
    • `region` (string): Region identifier

Disk Images

• list_disk_images
  • List available disk images on Civo
  • Inputs:
    • `region` (string, optional): Region identifier

• get_disk_image
  • Get details of a specific disk image
  • Inputs:
    • `id` (string): Disk image ID
    • `region` (string, optional): Region identifier

Network Management

• list_networks
  • List all available networks
  • Inputs: None

• create_network
  • Create a new network
  • Inputs:
    • `label` (string): Network label
    • `region` (string, optional): Region identifier

• rename_network
  • Rename an existing network
  • Inputs:
    • `id` (string): Network ID
    • `label` (string): New network label
    • `region` (string, optional): Region identifier

• delete_network
  • Delete an existing network
  • Inputs:
    • `id` (string): Network ID
    • `region` (string): Region identifier

Kubernetes Management

• list_kubernetes_clusters
  • List all Kubernetes clusters
  • Inputs:
    • `region` (string, optional): Filter by region
    • `page` (number, optional): Pagination page
    • `per_page` (number, optional): Results per page

• create_kubernetes_cluster
  • Create a new Kubernetes cluster
  • Inputs:
    • `name` (string): Cluster name
    • `region` (string): Region identifier
    • `network_id` (string): Network ID for the cluster
    • `nodes` (number): Number of worker nodes
    • `node_size` (string): Size of each node
    • `kubernetes_version` (string): Kubernetes version

• delete_kubernetes_cluster
  • Delete a Kubernetes cluster
  • Inputs:
    • `id` (string): Cluster ID
    • `region` (string): Region identifier

• list_kubernetes_versions
  • List available Kubernetes versions
  • Inputs: None

Resource Information

• list_sizes
  • List all available instance sizes
  • Inputs: None

• list_regions
  • List all available regions
  • Inputs: None

Configuration

Environment Variables

• `CIVO_API_KEY`: Your Civo API Key (required)
• `NODE_ENV`: Set to `production` to disable debug logging (optional)

Getting an API Key

1. Sign up for a Civo account if you don't have one.

2. Generate your API key following the API keys documentation

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository

2. Create a feature branch: `git checkout -b feature-name`

3. Make your changes and add tests

4. Run the test suite: `npm run test:ci`

5. Submit a pull request

Development Setup

git clone https://github.com/tao12345666333/civo-mcp.git
cd civo-mcp
npm install
npm run build

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

License

This MCP server is licensed under the MIT License. See the LICENSE file for details.