Skip to main content

Local Installation

Install and run the Hyperstack API MCP Server locally using Docker.

This guide explains how to locally install and run the Hyperstack MCP (Model Context Protocol) Server locally using Docker. It includes platform-specific setup instructions, container lifecycle management, and verification steps.

By the end of this guide, you will have a running MCP Server instance ready to connect to Claude Desktop or any MCP-compatible client.

Important: Live Infrastructure Changes & Data Loss Risk

This MCP server can create, modify, and delete real Hyperstack resources, which may incur charges on your account. Always review actions before confirming them. NexGen Cloud is not liable for any unintended resource usage, costs, or data loss resulting from the use of this tool. Use it at your own risk.

Install the MCP Server​

Follow these steps to install and run the MCP Server locally.

Prerequisites​

Before installing the MCP Server, ensure the following requirements are met:

  • Docker installed and running on your system
  • Port 8080 available and not in use by another service
  • A valid Hyperstack API key generated from the Hyperstack Console
note

Keep your API key secure. Do not commit it to source control or expose it in shared environments.

Part 1 – Install Docker (If Not Already Installed)​

If Docker is already installed, you may skip this step.

macOS​

Install Docker Desktop using Homebrew:

brew install --cask docker

After installation, open Docker Desktop and ensure the service is running.

Windows​

Download and install Docker Desktop from:

https://www.docker.com/products/docker-desktop

After installation, launch Docker Desktop and confirm it is running.

Linux (Ubuntu / Debian)​

Install Docker using apt:

sudo apt update
sudo apt install docker.io

Start and enable the Docker service:

sudo systemctl start docker
sudo systemctl enable docker

(Optional) Add your user to the docker group to run Docker without sudo:

sudo usermod -aG docker $USER

Log out and back in for group changes to take effect.

Part 2 – Run the MCP Server​

Start the MCP Server using the official Docker image.

macOS / Linux​

Run MCP Server
docker run --rm \
  --name hyperstack-mcp \
  -p 8080:8080 \
  -e HYPERSTACK_API_KEY=your_api_key_here \
  ghcr.io/nexgencloud/hyperstack-mcp-server:latest

Windows PowerShell​

docker run --rm `
  --name hyperstack-mcp `
  -p 8080:8080 `
  -e HYPERSTACK_API_KEY=your_api_key_here `
  ghcr.io/nexgencloud/hyperstack-mcp-server:latest

The HYPERSTACK_API_KEY environment variable is required and must contain a valid Hyperstack API key.

Part 3 – Verify Installation​

After starting the container, confirm that the MCP Server is running by checking the health endpoint.

Health Check
curl http://localhost:8080/health

A successful response should resemble the following:

{
  "status": "ok",
  "service": "hyperstack-mcp-server",
  "version": "0.1.0"
}

If the server does not respond:

  • Ensure Docker is running
  • Ensure port 8080 is not in use
  • Verify your API key is valid

Part 4 – Run in Detached Mode (Recommended)​

For persistent or production-style usage, run the container in detached mode with automatic restart:

docker run -d \
  --name hyperstack-mcp \
  -p 8080:8080 \
  -e HYPERSTACK_API_KEY=your_api_key_here \
  --restart unless-stopped \
  ghcr.io/nexgencloud/hyperstack-mcp-server:latest

This configuration:

  • Runs the container in the background
  • Automatically restarts on failure
  • Restarts after system reboot

Managing the MCP Server Container​

Stop the Server​

If running in foreground mode:

Ctrl + C

If running in detached mode:

docker stop hyperstack-mcp

View Logs​

docker logs hyperstack-mcp

Follow logs in real time:

docker logs -f hyperstack-mcp

Restart the Server​

docker restart hyperstack-mcp

Remove the Container​

docker rm hyperstack-mcp

Update to a New Version​

Pull the latest image:

docker pull ghcr.io/nexgencloud/hyperstack-mcp-server:latest

Stop and remove the old container, then re-run using the updated image.

Version Pinning

For production environments, consider pinning to a specific version instead of using latest.


Back to top

On this page