JumpServer Bastion (jms)

jms-client

A command-line client and MCP server for [JumpServer v4](https://docs.jumpserver.org/zh/v4/) bastion hosts. One self-contained binary that reaches the assets behind your bastion the same way the web terminal does — no VPN client, no SSH config, no per-host credentials.

Use it on its own to list assets, run commands, open shells and move files. Run jms mcp and an AI assistant (Claude Desktop, Claude Code, Codex, Cursor, pi, …) can do the same things through pooled, audited connections.

$ jms exec web-01 "systemctl is-active nginx"

active

English · 简体中文

Docs: Command reference · Addresses and proxies · Troubleshooting · Design

---

Why this exists

Reaching a bastion usually means a browser tab, or a ~/.ssh/config you maintain by hand. Neither composes with a shell pipeline, a build script, or an AI agent.

jms-client talks to the same two JumpServer APIs the web console uses (Core's REST API and KoKo's terminal gateway), so:

• Credentials never sit in a config file. The password and TOTP secret go to your OS credential store. The config file holds addresses and usernames only, so it is safe to sync, back up, or commit.
• One login serves many commands. Connections are pooled per server/asset/account/protocol and reused.
• The same config works inside and outside the office. Give a server both an internal and an external address and the client picks whichever answers.
• Everything is logged locally. Every command an AI agent runs is written to a JSONL audit stream you can read, follow, or join interactively.

Features

Requirements

• JumpServer v4 with the KoKo component reachable from your machine. JumpServer v3 and earlier are not supported.
• An account on that JumpServer with the assets you want to reach already authorized.
• The WebSocket backend requires nothing beyond a reachable HTTP(S) address. The SFTP and SSH features additionally require KoKo's SSH port (default 2222) to be open on the network path — many deployments only expose the web port, so check before relying on them.

Install

Prebuilt binaries (recommended)

Download the archive for your platform from Releases and put the jms binary (jms.exe on Windows) on your PATH.

checksums.txt in the same release lets you verify the download:

sha256sum -c --ignore-missing checksums.txt     # Linux

shasum -a 256 -c --ignore-missing checksums.txt # macOS

Scoop (Windows)

scoop bucket add mifazhan https://github.com/MiFaZhan/scoop-bucket

scoop install jms-client

Upgrade later with scoop update jms-client.

Go

Requires Go 1.25 or newer:

go install github.com/MiFaZhan/jms-client/cmd/jms@latest

From source

git clone https://github.com/MiFaZhan/jms-client

cd jms-client go build -o jms ./cmd/jms

For MCP clients only

If all you want is the AI integration and you would rather not manage a binary yourself, download `jms-client.mcpb` from Releases and open it with your MCP client (Claude Desktop and other MCPB-aware clients handle this by double-click). That single bundle contains the binaries for all six platform/architecture combinations; a bundled launcher picks the right one at startup.

Quick start

1. Store your server

$ jms config add bastion

Internal URL (http(s)://..., empty to skip): https://jumpserver.corp.example.com/ External URL (http(s)://..., empty to skip): Username: alice Password: Confirm password: TOTP secret (base32, empty to enter the code each time): Server "bastion" saved to /home/alice/.config/jms/config.toml Server "bastion" is now the default.

Either address may be left empty, but at least one is required. The credentials are validated against a reachable address before anything is written, so a mistyped password changes nothing on disk. The first server you add becomes the default.

2. Check it

$ jms config test

Server: bastion (default)

Endpoint URL Reachable Probe Login external https://jumpserver.corp.example.com/ yes 12ms ok

Credentials: keyring

config test probes every configured address and attempts a real login on each reachable one, so a network problem is reported separately from a rejected password, and you can see which addresses actually work. An address can pass the TCP probe and still fail the login — a VPN or proxy can accept the connection with nothing useful behind it.

3. Use it

$ jms ls                                   # assets you are authorized for

$ jms ls -q web # search by keyword $ jms exec web-01 "uptime" # one command, exit code passes through $ jms login web-01 # interactive shell (Ctrl+] to exit) $ jms sftp web-01:/var/log/app.log . # download $ jms sftp ./config.yml web-01:/etc/app/ # upload

Connecting an AI assistant (MCP)

jms mcp runs a Model Context Protocol server over stdio. Any MCP-capable client can then list assets, run commands and transfer files through the same pooled connections your shell uses.

{

"mcpServers": { "jms": { "command": "jms", "args": ["mcp"] } } }

Print this snippet at any time with:

jms mcp --print-config

Because the MCP process has no command-line flags (your client launches one long-lived process and cannot add arguments per call), the endpoint, backend and command timeout are steered with environment variables in that client entry:

{

"mcpServers": { "jms": { "command": "jms", "args": ["mcp"], "env": { "JMS_MCP_BACKEND": "ws", "JMS_MCP_EXEC_TIMEOUT": "10m" } } } }

Tools

An eighth tool, jms_pool_status, is registered when JMS_MCP_DEBUG=1 and reports the shape of the connection pool. It is for diagnosing the server, not for daily use.

Most tools accept optional server, config_path, account, protocol and timeout arguments. Remote specs use the form [@ ]: .

Two behaviours worth knowing when you write prompts for an agent:

• A non-zero exit code is not reported as a failure. jms_exec returns the command's output; the remote exit status is recorded in the audit log but not surfaced in the tool result. If your agent must branch on success, make the command say so (… && echo OK || echo FAIL).
• Commands are never replayed. If a call fails after the command was already delivered to the host, the client reports the error instead of retrying, because rm, reboot and friends are not idempotent. A dropped connection triggers one recovery attempt through a fresh login, but only for a command that produced no output at all.

Commands at a glance

Provisioning assets

JumpServer separates "an asset exists" from "a user may reach it": creating an asset records it, but only an AssetPermission exposes it to a user. That is why a new asset appears in jms asset list (the admin view) and not in jms ls (the per-user view) until it has been granted.

--grant-me on create does both steps in one command:

jms asset create "host-preview-01" 192.168.100.252 \

--account yunze --username yunze --password '…' --grant-me

Grants can also be managed separately:

jms asset grant "host-preview-01" --self      # or --account @ALL --protocol all

jms asset permissions "host-preview-01" # what grants this asset jms asset revoke "grant-host-preview-01" --yes

Deleting an asset does not delete the permissions that referenced it; the two are separate objects, so jms asset revoke is the command that ends access.

Target syntax is @ ; omitting @ uses the default server.

Full reference: docs/command-reference.md · 简体中文

Configuration

Con