How to Use Unity MCP CLI Commands via the HTTP API

Unity MCP CLI commands communicate with a running Unity MCP server over HTTP JSON-RPC when the server is started with --transport http, enabling language-agnostic automation through the /mcp endpoint.

The CoplayDev/unity-mcp repository provides a Python-based Command-Line Interface (CLI) that can execute Unity Editor operations through an HTTP JSON-RPC bridge. By configuring the transport mode to HTTP instead of the legacy stdio pipe, you can invoke Unity MCP CLI commands from any environment capable of making HTTP requests, including CI/CD pipelines, external scripts, and remote services.

Starting the Server with HTTP Transport

To enable Unity MCP CLI commands via the HTTP API, you must start the MCP server with HTTP transport mode. In Server/src/main.py, lines 120-150 parse the --transport flag and related environment variables, while lines 161-170 launch the HTTP server when the transport is set to "http".

Configuration via Environment Variables

Set UNITY_MCP_TRANSPORT=http to enable HTTP mode. The server reads UNITY_MCP_HTTP_HOST and UNITY_MCP_HTTP_PORT (defaulting to 127.0.0.1:8080) to determine the binding address for the JSON-RPC endpoint.

export UNITY_MCP_TRANSPORT=http
export UNITY_MCP_HTTP_HOST=0.0.0.0
export UNITY_MCP_HTTP_PORT=9090
uv run python -m src.main

CLI Arguments

Alternatively, pass the --transport flag directly when launching the server:

# Start with default host/port (127.0.0.1:8080)

uv run python -m src.main --transport http

# Custom configuration with remote hosting enabled

uv run python -m src.main --transport http \
    --http-host 0.0.0.0 \
    --http-port 9090 \
    --http-remote-hosted

The Server/src/transport/unity_transport.py file contains _is_http_transport() (lines 18-20), which checks config.transport_mode to determine if HTTP routes should be registered in the plugin hub.

CLI Client Connection Architecture

When running in HTTP mode, the CLI client implemented in Server/src/cli/main.py constructs JSON-RPC payloads and POSTs them to the HTTP endpoint rather than communicating through stdio pipes.

Connection Utility

The Server/src/cli/utils/connection.py module implements the low-level HTTP client used by the CLI. Line 112 provides clear error messaging when the HTTP endpoint is unreachable, handling connection retries and TLS configuration automatically.

When you run a command like mcp-cli status, the CLI performs an HTTP GET request to /status via the connection utility to verify server availability before executing tool commands.

Configuration Management

The Server/src/cli/utils/config.py module resolves connection parameters from both environment variables and CLI flags (--http-url, --http-host, --http-port). It constructs a ConnectionConfig object that determines the final endpoint URL (e.g., http://127.0.0.1:8080/mcp).

Executing CLI Commands Over HTTP

Once the server is running with HTTP transport, CLI commands follow a JSON-RPC flow through the endpoint defined in Server/src/transport/plugin_hub.py (line 147), which routes requests to the appropriate C# tools in Unity.

Single Commands

Standard CLI commands translate to JSON-RPC POST requests. For example, creating a GameObject:

mcp-cli gameobject create --name Cube

This serializes to the following JSON-RPC payload:

{
  "method": "gameobject.create",
  "params": {"name": "Cube"},
  "id": 1
}

The connection.py utility POSTs this to http://127.0.0.1:8080/mcp, where plugin_hub.py resolves the method to MCPForUnity/Editor/Tools/ManageGameObject.cs and executes it within the Unity Editor.

Other common operations include:

# List all open scenes

mcp-cli scene list

# Add a Rigidbody component to a specific object

mcp-cli component add --object-id 12345 --type Rigidbody

# Read the Unity console logs

mcp-cli console read

Batch Execution

For performance-critical workflows, the HTTP API supports batching multiple RPC calls in a single request via Server/src/services/tools/batch_execute.py:

mcp-cli batch_execute \
  --commands '[
    {"method":"gameobject.create","params":{"name":"Cube1"}},
    {"method":"gameobject.create","params":{"name":"Cube2"}},
    {"method":"component.add","params":{"object_id":1,"type":"Rigidbody"}}
  ]'

The server processes these commands sequentially and returns an array of results, reducing round-trip latency compared to individual HTTP requests for each operation.

Programmatic HTTP Integration

You can interact with the Unity MCP HTTP API directly from scripts without using the Python CLI wrapper, enabling integration with any language or tool that supports HTTP:

import httpx
import json

payload = [
    {"jsonrpc":"2.0","method":"gameobject.create","params":{"name":"Cube"}, "id":1},
    {"jsonrpc":"2.0","method":"component.add","params":{"object_id":1,"type":"Rigidbody"}, "id":2}
]

resp = httpx.post("http://127.0.0.1:8080/mcp", json=payload)
print(json.dumps(resp.json(), indent=2))

This approach allows you to execute Unity MCP CLI commands via the HTTP API from Bash scripts, Node.js applications, or cloud automation platforms.

Summary

• Start the server with --transport http or UNITY_MCP_TRANSPORT=http to enable the HTTP JSON-RPC endpoint at http://127.0.0.1:8080/mcp (configurable via UNITY_MCP_HTTP_HOST and UNITY_MCP_HTTP_PORT).
• CLI commands automatically use HTTP transport when configured, posting JSON-RPC payloads to the /mcp endpoint defined in Server/src/transport/plugin_hub.py.
• Batch execution reduces latency by sending multiple commands in a single HTTP request via the batch_execute tool in Server/src/services/tools/batch_execute.py.
• Direct HTTP access allows language-agnostic automation without requiring the Python CLI dependency, using standard JSON-RPC POST requests.

Frequently Asked Questions

What port does the Unity MCP HTTP API use by default?

The default port is 8080, bound to 127.0.0.1. You can override this using the --http-port flag or by setting the UNITY_MCP_HTTP_PORT environment variable before starting the server in Server/src/main.py.

Can I use the Unity MCP CLI without HTTP transport?

Yes, the CLI supports a legacy stdio pipe transport mode. However, HTTP transport is recommended for most use cases as it enables remote access, better error handling in Server/src/cli/utils/connection.py, and integration with non-Python environments.

How does the CLI handle connection errors to the HTTP endpoint?

The Server/src/cli/utils/connection.py module implements retry logic and provides clear error messages at line 112 if the HTTP endpoint is unreachable. Ensure the server is running with the correct transport mode and that the host/port configuration matches between the server and CLI config.

Is batch execution more efficient than individual CLI commands?

Yes. The batch_execute tool in Server/src/services/tools/batch_execute.py processes multiple JSON-RPC requests in a single HTTP POST to http://<host>:<port>/mcp, reducing network overhead and round-trip latency compared to executing separate CLI commands sequentially.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}