Hyperia CLI

The hyperia command‑line tool is installed alongside the library and lets you run, test, and package MCP servers without touching Python code.

$ hyperia --help

🚦 Command Matrix

Command
Purpose
Dependency Handling
Typical Stage

run

Launch a Hyperia server or proxy

Uses current environment. You ensure deps

Prod & local quick runs

dev

Spin up server + Inspector UI

Creates isolated env; specify extras via --with

Interactive testing

install

Package server for Claude Desktop (STDIO)

Isolated env; extras via --with

End‑user distribution

version

Print version info

n/a

Diagnostics

hyperia <command> [options]

1 · run — One‑Shot Runner / Proxy

Run local code or create a quick proxy to a remote MCP.

hyperia run server.py          # local file
hyperia run server.py:mcp_alt  # explicit object name
hyperia run https://api.example.com/mcp  # proxy remote → stdio

Core Flags

Flag
Short
Description

--transport

-t

stdio (default), streamable-http, sse (deprecated)

--host

Bind host for HTTP/SSE (default 127.0.0.1)

--port

-p

Bind port (default 8000)

--log-level

-l

DEBUG / INFO / WARNING / ERROR / CRITICAL

When passing a file path, the CLI ignores any if __name__ == "__main__": block and directly calls .run() on the discovered object (mcp, server, or app). This lets you override transport without editing code.

Examples

# Override transport defined in code
hyperia run server.py -t streamable-http -p 9000

# Proxy remote HTTP server as local STDIO (for IDE)
hyperia run https://store.example.com/mcp

# Verbose logs
hyperia run backend.py -l DEBUG

2 · dev — Inspector + Sandbox Env

Launches server in an isolated virtual env and opens the MCP Inspector GUI.

hyperia dev server.py -e . --with pandas --with matplotlib

  • Defaults to STDIO transport (Inspector dropdown).

  • Not for HTTP testing—start server separately with run -t streamable-http then connect Inspector manually.

Flag
Short
Description

--with-editable <dir>

-e

Install local project in editable mode (requires pyproject.toml)

--with <pkg>

Extra pip packages (can repeat)

--inspector-version <ver>

Pin Inspector release

--ui-port <port>

Port for Inspector web UI

--server-port <port>

Port for Inspector proxy backend

3 · install — Package for Claude Desktop

Packages server into Claude Desktop’s plugin directory (always STDIO transport).

hyperia install server.py -n "My Analysis" -e . --with numpy --env-var API_KEY=123
Flag
Short
Purpose

--name

-n

Friendly display name

--with-editable

-e

Editable project path

--with

Extra packages (repeatable)

--env-var KEY=VAL

-v

Inject env var

--env-file <file>

-f

Load vars from .env

Claude will launch the server per session under STDIO regardless of code transport settings.

4 · version

Print versions of Hyperia, MCP spec, Python, and platform.

$ hyperia version
Hyperia:      0.5.0
MCP spec:     2025‑03‑26
Python:       3.12.2
Platform:     macOS‑15.4‑arm64

5 · Advanced Tips

  • Shebang stub – add #!/usr/bin/env hyperia run at top of script for UNIX executable.

  • .hyperiarc – place default CLI flags in project root to avoid long commands.

  • CI/CD – run hyperia run inside Docker to smoke‑test Streamable HTTP startup (curl -f http://localhost:8000/mcp/health).

PreviousAuthorizationNextClient Overview

Last updated