MCP Server

System Bridge includes a Model Context Protocol (MCP) server, letting agents and other MCP clients query your system and trigger actions.

The server runs over a WebSocket at ws://{host}:9170/api/mcp. Replace {host} with the hostname or IP of the machine running System Bridge; the port can be changed with the SYSTEM_BRIDGE_PORT environment variable. The connection is authenticated with your API token, passed either as a token query parameter or an Authorization: Bearer {token} header. A missing or invalid token is rejected with 401 Unauthorized. See how to find your token.

Setup

Agents launch MCP servers as a local command and talk to them over stdio. Because System Bridge serves MCP over a WebSocket, a bridge such as websocat is needed to pipe stdio to the WebSocket.

With websocat installed, add System Bridge to your agent’s MCP config:

{
  "mcpServers": {
    "system-bridge": {
      "command": "websocat",
      "args": ["ws://localhost:9170/api/mcp?token=YOUR_TOKEN"]
    }
  }
}

Replace localhost with the host running System Bridge if the agent is on another machine.
Replace YOUR_TOKEN with your API token. See how to find your token.

If you sync one config across several machines, hardcoding a token doesn’t travel well. Use a small wrapper script that reads the token from system-bridge client token at launch and execs websocat, then point command at it so each machine uses its own token automatically:

{
  "mcpServers": {
    "system-bridge": {
      "command": "system-bridge-mcp"
    }
  }
}

Tools

`system_bridge_get_data`

Get current system information from one or more data modules. The tool returns each requested module’s latest data as JSON.

modules (required): An array of module names to fetch.

Available modules:

Module	Description
`battery`	Charge level, charging state, and time remaining.
`cpu`	Usage, frequency, core counts, and per-core load.
`disks`	Mounted devices, partitions, and used/free space.
`displays`	Connected displays, resolution, and refresh rate.
`gpus`	GPU model, load, memory, and temperature.
`media`	Currently playing media: title, artist, and playback state.
`memory`	Physical and virtual memory usage.
`networks`	Network interfaces, addresses, and throughput.
`processes`	Running processes with CPU and memory usage.
`sensors`	Hardware sensors such as temperatures and fan speeds.
`system`	Hostname, OS, uptime, users, and version details.

Example arguments:

{ "modules": ["cpu", "memory", "battery"] }

`system_bridge_send_notification`

Send a desktop notification to the machine running System Bridge.

title (required): The notification title.
message (required): The notification body text.
icon (optional): An icon name to display with the notification.

Example arguments:

{ "title": "Build finished", "message": "All tests passed", "icon": "dialog-information" }

`system_bridge_media_control`

Control playback of the system’s current media session.

action (required): The action to perform. Must be uppercase.

Available actions:

Action	Effect
`PLAY`	Resume playback.
`PAUSE`	Pause playback.
`STOP`	Stop playback.
`NEXT`	Skip to the next track.
`PREVIOUS`	Return to the previous track.
`VOLUME_UP`	Raise the volume.
`VOLUME_DOWN`	Lower the volume.
`MUTE`	Toggle mute.

Example arguments:

{ "action": "PAUSE" }