Skip to main content
Glama
Yoliani

rex-mcp

by Yoliani
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

rex-mcp

Let an AI agent read, type into, and run commands in Rex terminal blocks on your own machine, through the rex CLI.

rex-mcp is an MCP server over stdio. Any MCP client that spawns local servers (pi, Claude Desktop, Cursor desktop, and others) can connect to it. Ask the agent to list your sessions, read a block's screen, type a command into a block, or run a command and wait for it to finish.

It follows the design of herdr-mcp: one passthrough tool that runs a fixed allowlist of CLI verbs, plus a skill tool that serves the CLI's own guide. The differences are the transport (stdio instead of HTTP with a bearer token) and the CLI underneath.

What you need

  • Rex installed, with its app or server available on this machine. The CLI finds the local server on its own; like plain rex, a call may autostart a missing server.

  • Node.js 22 or later.

  • rex on the PATH of the process that spawns the MCP server, or REX_MCP_BINARY pointing at it. Inside Rex terminals this is automatic; outside, check which rex.

Related MCP server: Shell Server

Install

git clone <this repo> && cd rex-mcp
npm install
npm test

Run it

The server speaks MCP over stdio, so a client spawns it; running it by hand just waits for JSON-RPC on stdin. Point a client's MCP config at it:

{
  "mcpServers": {
    "rex-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/rex-mcp/bin/rex-mcp.mjs"]
    }
  }
}

Or install the package and use the binary: npm install -g rex-mcp (or just link from a checkout), then set "command": "rex-mcp".

Optional environment variables:

Variable

Default

Meaning

REX_MCP_BINARY

rex

Path to the rex executable. REX_BIN_DIR is used as a fallback parent directory.

REX_MCP_WAIT_MAX

90000

Wait ceiling in milliseconds for wait calls.

Tasks

just drives everything; run just with no arguments to list recipes.

Recipe

What it does

just install

Install dependencies.

just test

Run the test suite, no Rex server needed.

just run

Start the server on stdio.

just live

End-to-end probe against the real Rex server (creates and closes two blocks).

just pack

Build the npm tarball into dist/.

just link

npm link so rex-mcp is on PATH.

just publish

Publish the current version to npm.

just clean

Remove dist/.

Package and release

npm pack ships only bin/, src/, README and LICENSE (see the files field), and prepublishOnly runs the tests first.

CI (.github/workflows/ci.yml) runs the suite on push and pull requests across Ubuntu and macOS with Node 22 and 24.

Releases (.github/workflows/release.yml) run when you push a v* tag: tests, tarball, GitHub release with the tarball attached, then npm publish. Setup, once:

  1. Push the repo to GitHub and git init + commit if you have not already.

  2. Create an npm automation token and add it as the repository secret NPM_TOKEN.

  3. Cut a release: npm version patch && git push --follow-tags.

For a local release without CI: just pack, then npm publish (or just publish).

Tools

rex runs one rex command. Supply exactly one of args (an array of strings) or command (a quote-only string; no shell operators, substitution, or expansion).

Allowed verbs, with what the bridge does to them:

Verb

Notes

list, ls

List sessions.

session ls/inspect, window ls/inspect

Discovery.

block ls/inspect/types/capture/send/send-key

Inspect and drive one block.

client ls/inspect

See connected clients.

api ls/list/describe

Read the server's control API surface.

capture

Print a block's screen (text, html or vt). An explicit target is required.

send, send-key

Type into a terminal. An explicit target is required: -b BLOCK, -w WINDOW, or -s SESSION.

run

Start a command in a new block; add --wait for its exit status and --keep-open to read its output with capture afterwards.

wait

Block until a target ends. The bridge pins --for at the ceiling (default 90 s).

help

Read command syntax.

Listing and inspection calls get --json appended, so output is stable to parse. Failure envelopes carry a code, a message, and recovery advice in next. Rex's exit statuses map as: 2 invalid arguments, 3 target not found or ambiguous, 4 server unreachable, 130 cancelled.

The bridge runs outside any Rex terminal, so there is no default session or block: scope calls explicitly. Two patterns cover most work:

# Run a command and read its output
rex run -s SESSION --wait --keep-open -- CMD   # exit status comes back; block stays open
rex capture -b BLOCK --trim                    # the command's output

# Work in an existing terminal
rex send -b BLOCK 'make test'                  # type; delivery is not completion
rex wait BLOCK --for 90s                       # exit status when the command ends

rex_skill returns the installed CLI guide verbatim. Read it once before the first rex call.

What is disabled

do (Lua), events, block stream, api call, attach, every create, layout, rename, close, and kill command, and -S server routing. The bridge drives the local Rex server only. This keeps an agent from deleting sessions, rearranging layout, or reaching other hosts through the MCP surface.

Wait semantics

Rex blocks are terminals, not agents. wait TARGET returns when the target's child process exits, with that exit status; wait --for bounds the wait and returns non-zero on timeout. There is no idle/working/done state to poll. To check on a running command, capture the block and read the screen; to wait for a command to finish, call wait again with the same target. On wait_timeout, capture first: the reply may already be on screen.

Risks

The rex tool types into your real terminals and starts real processes with the permissions of the MCP client. A malicious prompt or document can steer an agent into using that access. Terminal output may contain passwords, keys, or private work, and a capture can surface them into agent context. The allowlist reduces accidents, not intent; treat a connected agent as someone typing at your keyboard.

Development

just test
just live

The tests cover argument splitting and allowlist rules, wait budgeting, exit-status mapping, the spawn runner, and a full MCP handshake over stdio against a fake rex binary, so they run without a Rex server. scripts/live.mjs is the same handshake against your real Rex server; it creates two short-lived blocks and closes them at the end.

Credits

rex-mcp is inspired by herdr-mcp by Igor Warzocha, the MCP bridge for Herdr. The tool design (a passthrough CLI tool with an allowlist plus a skill tool) and parts of the bridge code are adapted from it, under the MIT licence. rex-mcp targets Rex instead of Herdr, runs over stdio instead of an authenticated HTTP tunnel, and waits on terminal process exits instead of agent state.

Licence

MIT © Edgardo Yoliani. Contains code adapted from herdr-mcp, MIT © Igor Warzocha; see the notice in LICENSE.

Available Tools

2 tools
rexRex CLIA

Run the rex CLI against the local Rex server. This bridge runs outside any Rex terminal, so there is no default session or block: scope every call explicitly. Discovery: list (sessions), then block ls -s SESSION or session inspect -s SESSION. Act: capture -b BLOCK reads a terminal screen; send or send-key types into a terminal and needs an explicit target (-b BLOCK, -w WINDOW or -s SESSION); run -s SESSION -- CMD starts a command in a new block, with --wait to block until it exits (its exit status becomes the call's exit status) and --keep-open to keep the block for capture afterwards; wait TARGET blocks until a block, window or session ends, capped at 90000 ms; help shows syntax; rex_skill reads the full guide. To run a command and read its output: run -s SESSION --wait --keep-open -- CMD, then capture -b BLOCK. On wait_timeout, capture the target (a reply may already be on screen) and repeat wait with the same target if the exit status is still needed; otherwise carry on and check back later. send confirms typing, not that a command finished. Supply exactly one of args (array of strings) or command (quote-only string). Disabled here: do (Lua), events, block stream, api call, attach, and create, layout, rename, close or kill commands; also -S server routing, because this bridge drives the local Rex server only.

ParametersJSON Schema
NameRequiredDescriptionDefault
argsNo
commandNo

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does so: it discloses the absence of a default session/block, the 90000 ms wait cap, that --wait propagates the command's exit status, and that 'send confirms typing, not that a command finished.' It also enumerates disabled subcommands and the disabled -S server routing, which prevents predictable failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and the scoping constraint, and groups remaining content under Discovery/Act headings. It is dense with semicolon-chained clauses and long enough to risk skimming, but nearly every sentence carries operational information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a high-complexity tool with no annotations and no output schema, yet the description covers invocation, target scoping, the run→capture composition, timeout handling, pushback on send semantics, and unsupported operations. Nothing material for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does: it states the mutual-exclusivity rule ('exactly one of args (array of strings) or command (quote-only string)') and explains the semantics of the embedded flags an agent will put inside args (-b, -w, -s, --wait, --keep-open). This is substantially more than the bare schema types convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run the rex CLI against the local Rex server') and immediately frames the execution context (outside any Rex terminal). It also distinguishes itself from the only sibling by noting rex_skill holds the full guide, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit discovery-then-act workflow (list → block ls / session inspect → capture/send/run/wait) plus a named composition pattern: run with --wait --keep-open, then capture -b BLOCK. It also gives a branch for wait_timeout, clarifying a decision an agent would otherwise have to guess at.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rex_skillRex CLI guideA

Read the installed Rex CLI guide verbatim (about 20 KB). Read this before the first rex call; it documents commands, targets and flags for the installed Rex version.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does well: it discloses the payload size (~20 KB, relevant to context budget) and that content is returned verbatim rather than summarized. It stops short of stating explicitly that the operation is a safe read with no side effects, but 'Read' strongly implies it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both earning their place: the first gives the payload and its size, the second gives the timing rule. The most actionable instruction is placed last for emphasis without burying the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, output-schema-less documentation fetch, the description supplies everything needed: what is returned, its approximate size, and when to invoke it. Nothing further is required to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4 and there is nothing the description could add. It correctly spends no words on parameter explanation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Read'), a specific resource (the installed Rex CLI guide), and the exact behavior ('verbatim, about 20 KB'). By naming the sibling 'rex', an agent can immediately tell this is the documentation lookup rather than the CLI executor.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to call it: 'Read this before the first rex call.' That is a clear ordering/context trigger relative to the only sibling, leaving nothing to inference about sequencing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv0.1.0
    • First observedrex
    • First observedrex_skill
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.4/5.0

Scored across 2 tools

Disambiguation4/5

rex_skill only retrieves the installed Rex CLI guide, while rex executes scoped CLI commands against the local server; the documentation-vs-execution split is understandable. There is minor overlap because rex also exposes help subcommands and refers back to rex_skill, but the primary purposes are distinct.

Naming Consistency3/5

Both tools share the rex namespace, but the set does not follow a predictable verb_noun pattern: rex is a bare command name and rex_skill is a noun-like guide tool. The names are readable but not self-explanatory without descriptions.

Tool Count3/5

Two tools is thin for a CLI bridge, but one is an omnibus executor and the other provides necessary version-specific documentation. Each earns its place, though the surface is intentionally narrow rather than comfortably scoped.

Completeness3/5

The set covers discovery, inspection, capture, send/send-key, run, wait, and help, so core terminal interaction is available. However, lifecycle operations such as create, close, kill, rename, and layout are explicitly disabled, along with events/streaming, API calls, and server routing, leaving notable gaps.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • terminal-mcp

    ParthKapoor-dev
    F
    license
    Not graded
    quality
    Not graded
    maintenance
    A secure and pluggable MCP server to run terminal commands on your local machine or cloud server — remotely, safely, and with LLMs or agentic clients.
    -

  • Shell Server

    joandiazcapell
    F
    license
    A
    quality
    D
    maintenance
    A lightweight MCP server that provides AI assistants with access to a system's terminal through a secure terminal tool. It enables users to execute shell commands and receive stdout, stderr, and exit codes directly within an MCP-compatible client.
    1
    -