Skip to main content
Glama

ModemBox

CI version license Docker Pulls

Plug a USB modem into a Linux box and run ModemBox. Send and read SMS, check the SIM and radio, and run AT commands from the browser, over HTTP, or through MCP. With supported hardware you can place and answer calls, listen, talk through the browser microphone, and play a WAV clip into the call.

Open a second browser and watch the same inbox, calls, and activity update live. A bearer token controls access by default. SQLite keeps the inbox and encrypted SIM PINs.

Contents

Related MCP server: Hermes Phone Agent

Quick start

Plug in your USB modem on a Linux host with Docker Compose, curl, and OpenSSL.

curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-modembox/main/install.sh | bash
modembox start

If your shell cannot find modembox, run ~/.local/bin/modembox start.

The installer generates MODEMBOX_TOKEN on first install and saves it in ~/.config/modembox/.env. Open http://localhost:8000 and paste the value into the Access token field.

Fresh installs use psyb0t/modembox:latest and store the database and PIN key under ~/.config/modembox/data/.

Use modembox upgrade to pull the current image tag, modembox upgrade --version vX.Y.Z to pin a release, or modembox uninstall to remove the stack and keep your data.

For tailnet HTTPS, set MODEMBOX_TAILSCALE_ENABLED=true in that same .env and run modembox start. The installation guide covers Tailscale login, system installs, and direct Docker.

Hardware

ModemBox reads the modem's manufacturer, model, and firmware, then checks what it can do. The tested Huawei E173 layout has one serial port for commands and another for call audio. ModemBox detects known Huawei USB layouts. For other devices, map the control port and check the capabilities shown in the console.

Keep host modem software off the ports ModemBox uses. See the device guide for port mapping, SIM PINs, and voice support.

Agent integrations

Point your Streamable HTTP MCP client at http://localhost:8000/mcp. When authentication is on, use the same bearer token as the web console. Call list_modems first to see what the device supports.

Once released, install the skill and optional stdio bridge through the shared catalogs:

claude plugin marketplace add psyb0t/agents
claude plugin install modembox@psyb0t

codex plugin marketplace add psyb0t/agents
codex plugin add modembox@psyb0t

openclaw skills install @psyb0t/docker-modembox
openclaw plugins install clawhub:@psyb0t/modembox

For the stdio bridge, set MODEMBOX_URL to the base URL and MODEMBOX_TOKEN to the bearer token when auth is enabled. The bridge appends /mcp. See MCP and agent integrations.

Documentation

The full docs are at psyb0t.github.io/docker-modembox.

Guide

What you'll find

Installation

Compose, direct Docker, upgrades, and data storage

Devices and configuration

Modem profiles, SIM PINs, and runtime settings

REST and WebSockets

Endpoints, live events, and call audio frames

MCP and agent integrations

Client setup and the list of tools

Development

make lint
make test
make build

Tests run in Docker. Unit tests cover codecs and discovery. Integration tests use a simulated modem on a Linux pseudo-terminal with the real API and SQLite database. The browser test drives SMS and call controls in Stealthy Auto Browse.

make test-real MODEMBOX_TEST_DEVICE=/dev/ttyUSB2 reads identity, SIM status, registration, and voice capability from a selected physical modem. It does not send SMS, place calls, or submit a PIN. Run it with the selected control port free.

For a physical SMS reply check, set MODEMBOX_TEST_NUMBER to the test phone's international number in a private .env.test file. Set MODEMBOX_TEST_PIN if the modem's SIM needs unlocking. Run make test-real-sms-receive MODEMBOX_TEST_DEVICE=/dev/ttyUSB2 with the control port free. The modem texts the test phone and asks for a TEST1 reply. Set MODEMBOX_TEST_SMS_TEXT to use another reply. The test passes when a new SMS from the test phone matches the expected text exactly. It fails if the modem rejects the invitation or if no match arrives within five minutes of submission.

Released images target Linux amd64 and arm64.

A push to main runs checks and publishes :latest and :sha-<commit>. A version tag waits for the successful main run for its commit, promotes that image to the version tag, and publishes the GitHub release, ClawHub packages, and MCP registry metadata.

Sponsor

Sponsor on GitHub

License

AGPL-3.0-only.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP-capable clients to interact with UniFi Site Manager and UniFi Dream Machine telemetry, providing tools for client details, ISP metrics, and more.
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to discover connected gadgets, read their state and events, and route commands to them over versioned device contracts on local USB and TCP transports. Ships with a configurable software simulator so device interactions can be exercised without physical hardware.
      6
      Apache 2.0