home / mcp / hello3d mcp server

Hello3D MCP Server

Provides an MCP bridge between clients and a 3D visualization frontend, enabling real-time model control via WebSocket with multi-session support.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "aidenlab-hello3dmcp-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "WS_PORT": "3001",
        "MCP_PORT": "3000",
        "BROWSER_URL": "http://localhost:5173"
      }
    }
  }
}

You set up a dedicated MCP server that bridges Model Context Protocol clients with a 3D model frontend, enabling real‑time control, multi‑user sessions, and stateful interactions through WebSocket or HTTP transports.

How to use

You connect MCP clients to this server to send tool calls that modify or query the 3D scene. The server supports two transport modes: STDIO for local subprocess usage and HTTP/SSE for remote clients. When a client is connected, commands are forwarded to the frontend via WebSocket in real time, and the frontend applies changes to the 3D visualization immediately.

How to install

Follow these concrete steps to get the MCP server up and running.

# Prerequisites
node -v
npm -v

# 1. Install dependencies
npm install

# 2. Configure environment (optional)
cp .env.example .env
# Edit .env with your settings

# 3. Start the server (STDIO mode)
npm start
# or
node server.js
```

The server starts with the MCP HTTP endpoint at http://localhost:3000/mcp and the WebSocket bridge at ws://localhost:3001.

Configuration and general notes

Configure how the server exposes endpoints and browser connections by setting environment variables or passing command-line options. The default browser URL is http://localhost:5173, and typical ports are 3000 for MCP and 3001 for WebSocket. You can override these with a .env file or via command-line arguments.

# Example .env
MCP_PORT=3000
WS_PORT=3001
BROWSER_URL=http://localhost:5173
```

# Overriding with CLI
node server.js --browser-url https://your-frontend.example

Troubleshooting and tips

If you run into connection or port issues, verify that the MCP endpoint is accessible, ensure WebSocket connections are allowed by your hosting environment, and confirm the frontend is running and listening on the specified port. For remote access, consider tunneling or exposing a public URL and ensuring the /mcp path is reachable.

Tool and endpoint overview

The server provides a wide set of tools to control model color, size, lighting, camera, and scene properties. Frontend updates occur in real time when tools are called.

Developer notes

If you are extending the server, register new tools in the server code and ensure the frontend handles the corresponding WebSocket messages to apply the changes.

Available tools

change_model_color

Change the color of the 3D model using a color value (hex or named color)

change_model_size

Change the uniform size of the model

scale_model

Scale the model independently along the x, y, and z axes

set_model_rotation

Set the model rotation using Euler angles

get_model_color

Query the current color of the model

get_model_scale

Query the current scale of the model

get_model_rotation

Query the current rotation of the model

set_key_light_intensity

Adjust the key light intensity

set_key_light_position_spherical

Set the key light position in spherical coordinates

set_camera_fov

Set the camera field of view

change_background_color

Change the scene background color

get_background_color

Query the current background color

get_browser_connection_url

Get the URL to connect the browser to the 3D app