RunLoop MCP Server

March 10, 2025 · View on GitHub

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with RunLoop development environments and tooling. This server implements Anthropic’s MCP specification to allow Claude Desktop to programmatically:

  • Create and manage RunLoop’s isolated development environments (devboxes)
  • Deploy preconfigured environments using blueprints
  • Define and execute test scenarios
  • Run AI performance benchmarks
  • Manage source code repositories

Table of Contents

  1. Features
  2. Installation
  3. Usage
  4. Development
  5. Debugging
  6. License

Features

  • Complete Programmatic Access: Offers Claude Desktop full access to the RunLoop API.
  • Zod-Based Validation: Uses schemas generated by orval to validate inputs from Claude.
  • Infrastructure Management: Allows provisioning, configuration, and teardown of devboxes.
  • Blueprint Deployment: Facilitates consistent environment setup via blueprints.
  • Test and Benchmark Tooling: Streamlines AI performance tests and scenario-based testing.

Installation

Clone the Repository

git clone https://github.com/IvanPedroza/runloop-mcp.git
cd runloop-mcp

Install Dependencies

npm install

Add Configuration for Claude Desktop

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "runloop": {
      "command": "node",
      "args": ["<YOUR-PATH-HERE>/build/index.js"],
      "env": {
        "RUNLOOP_API_KEY": "API-KEY"
      }
    }
  }
}

Usage

Build the Project

npm run build

This compiles the TypeScript code and makes the output file executable.

Run the Server

node build/index.js

The server will listen on stdio to communicate with Claude Desktop. You do not have to run the server, as it will run when you launch Claude Desktop via your config file.

Integrate with Claude Desktop

Ensure your claude_desktop_config.json is configured see Installation.

Launch Claude Desktop. The server will automatically connect once started.

Development

This project uses several tools to streamline development:

orval: Generates Zod schemas from OpenAPI specs.

Biome: Ensures consistent code style and identifies potential issues.

Zod: Validates AI inputs at runtime.

NPM Scripts

build: Compiles the TypeScript code and makes the output file executable.

watch: Watches and recompiles TypeScript files on changes.

inspector: Runs the MCP Inspector tool on the built server.

lint: Runs Biome to check and format code.

zod: Generates Zod schemas from an OpenAPI spec using orval.

Debugging

Because MCP servers communicate over stdin / stdout, debugging can be tricky. We recommend using the MCP Inspector included as an npm script:

npm run inspector

The inspector will print a URL in the console. Visit that URL in your browser to explore incoming/outgoing messages, monitor logs, and troubleshoot issues in real-time.

License

This project is licensed under the MIT License, allowing for free use, modification, and distribution of the code.