home / mcp / cloudlab mcp server

CloudLab MCP Server

MCP server for managing CloudLab/Emulab experiments

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ardagurcan-cloudlab-mcp": {
      "command": "node",
      "args": [
        "/path/to/cloudlab-mcp/dist/index.js"
      ],
      "env": {
        "CLOUDLAB_API_URL": "https://www.emulab.net:43794",
        "CLOUDLAB_TOKEN_PATH": "${TOKEN_PATH}"
      }
    }
  }
}

You run a CloudLab MCP Server to manage your CloudLab experiments through an MCP client. It lets you create, list, inspect, and control experiments and their nodes from automated tools, enabling seamless AI-assisted experiment management.

How to use

Use an MCP client to connect to the CloudLab MCP Server and perform common operations like creating experiments from profiles, listing all experiments, getting detailed status, and performing node-level actions such as rebooting, reloading, or extending experiments. You interact with the server through the provided MCP command surface, which is exposed locally via a standard input/output (stdio) interface that you start from your environment or an automation tool that invokes the node process directly.

How to install

Prerequisites: you need Node.js 18 or later.

Step 1: Set up your project and install dependencies.

npm install
npm run build

How to install

Step 2: Start the MCP server locally to obtain the runtime executable you will connect to from your MCP client. The server is run as a Node.js process that executes a built distribution.

If you keep the default build output path, you can run the server with the following command.

node /path/to/cloudlab-mcp/dist/index.js

Additional content

Configuration relies on a CloudLab JWT token for API access. You can set the token path via an environment variable or place the token file in a known location.

Configuration and security

Token management is essential for secure operation. The server looks for a CloudLab JWT token in a prioritized list of locations and avoids committing tokens to version control.

Notes and troubleshooting

If you run into token-related issues, verify the token location and permissions. Ensure the token file is readable by the user running the MCP server and that the path is correctly exposed to the runtime environment.

Examples and actions

The MCP server supports a variety of actions you can perform through the MCP client, such as creating experiments from profiles, listing experiments, and managing node states (reboot, reload, powercycle). Use your MCP client to invoke these actions against the CloudLab MCP Server.

Environment variables

Two environment variables are used to configure access and endpoints for CloudLab: CLOUDLAB_TOKEN_PATH for a custom token file path and CLOUDLAB_API_URL to override the API endpoint.

Tools and capabilities

The server provides a set of capabilities you can invoke via the MCP client, including creating experiments, listing experiments, retrieving detailed experiment status, rebooting specific nodes or all nodes in an experiment, reloading or reimaging nodes, performing a hard powercycle, extending experiment time, and terminating experiments.

Available tools

create_experiment

Create a new experiment from a profile.

list_experiments

List all your CloudLab experiments.

get_experiment

Get detailed status of an experiment.

reboot_node

Reboot a specific node in an experiment.

reboot_all_nodes

Reboot all nodes in an experiment.

reload_node

Reload or reimage a node to its disk image.

powercycle_node

Power cycle a node (hard reboot) for unresponsive nodes.

extend_experiment

Extend the expiration time of an active experiment.

terminate_experiment

Terminate and clean up an experiment.