jms-client

A command-line client and MCP server for JumpServer 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.

Related MCP server: Shuttle

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 <asset>[@<server>]:<path>.

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 <asset>@<server>; omitting @<server> uses the default server.

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

Configuration

Config lives at:

Override with the --config flag or the JMS_CONFIG environment variable. Relocating the file also relocates the audit directory, because both live beside it.

version = 2
default_server = "bastion"

# Optional global proxy policy. Omitted means: connect directly.
# proxy = "socks5://127.0.0.1:1080"

[servers.bastion]
internal = "http://192.168.1.10:2280/"          # internal address (optional)
external = "https://bastion.example.com/"       # external address (optional)
username = "alice"

# prefer = "external"       # try this address first; default is internal
# pin = "internal"          # use only this address: no probing, no failover
# ssh_port = 2222           # KoKo SSH port if not the default
# proxy = "direct"          # force a direct connection for this server

[servers.staging]
external = "https://jumpserver.staging.example.com/"
username = "alice"
prefer = "external"

Every field except the username is optional, but at least one address is required.

When a server has both addresses, the client probes them in turn and logs into the first that answers, remembering the last-good one for ten minutes. The client connects directly by default and ignores HTTP_PROXY and friends — a proxy must be configured explicitly.

Details: docs/networking.md · 简体中文

Credentials

The config file is written atomically and never contains a credential, which is what makes it safe to sync between machines. Acknowledge the boundary this implies: it protects against file leakage and copying a config to another machine, not against a malicious process running as the same user.

For headless environments (containers, CI, WSL without a Secret Service) there are environment-variable fallbacks. The environment takes precedence over the credential store.

Aliases are upper-cased and - becomes _, so bastion-eu becomes JMS_PASSWORD_BASTION_EU. An exported-but-empty variable counts as unset rather than as an empty password. If neither source has a credential, the command fails with a message naming the variable to set — it never falls back to storing a plaintext password.

A locked credential store (the usual state of a GNOME Keyring with no desktop session) fails in milliseconds with a message naming the environment variable to set — see troubleshooting.

Environment variables

Terminal backends

JumpServer's KoKo component offers two terminal channels, and jms-client speaks both.

Select it with --backend ssh, or --backend auto to try SSH and fall back to WebSocket. The backend that last succeeded for an address is remembered in state.json, so a cold start goes straight to it instead of waiting out a handshake on a blocked port. In MCP, the remembered backend also lets the process recover from a stale connection without a restart.

Tools that need SFTP — jms sftp, jms_sftp_upload, jms_sftp_download, jms_sftp_relay — require KoKo's SSH port to be open. If file transfers hang or fail while exec works fine, that port is the first thing to check.

Audit log

Every command is recorded as one JSON object per line:

{"ts":"2026-10-05T14:32:01.123+08:00","pid":12345,"actor":"mcp:pi","kind":"exec.end","server":"prod","asset":"web-01","backend":"ssh","endpoint":"external","command":"systemctl status nginx","exit_code":0,"duration_ms":118,"output_bytes":2140,"preview":"● nginx.service ...","pool":"hit","idle_ms":68000}

Files are written to <config dir>/audit/audit-YYYYMMDD-<pid>.jsonl, one file per process, with 0600 permissions on both the directory and the files. Per-process files avoid the Windows problem of several processes appending to one locked file, and they let a long-running host and a one-shot CLI invocation coexist.

Event kinds: exec.start, exec.end, pool.cold, pool.hit, pool.evict, pool.reap, session.login, session.relogin, endpoint.select, error.

Output previews are truncated to 4096 bytes by default (JMS_AUDIT_PREVIEW_BYTES, or JMS_AUDIT_FULL=1 for everything). Nothing in the log interpolates a credential.

Limitations

• JumpServer v4 only. The v3 authentication and terminal APIs differ.

• jms sftp does not do recursive copies or asset-to-asset relay. Use the MCP jms_sftp_relay tool for the latter, or relay through your local machine.

• 32-bit platforms are not built. Only x86_64 and arm64.

• The audit log is local. Nothing is forwarded to a central collector; ship the files yourself if you need to aggregate.

• A jump-host chain (proxy/jump through another asset) is not implemented.

When something goes wrong: docs/troubleshooting.md · 简体中文

Development

go build ./...     # compile
go test ./...      # unit and protocol-regression tests
go vet ./...
gofmt -l .         # must print nothing

Integration tests connect to a real JumpServer and are gated behind an environment variable; without it they skip, so a fresh clone is green:

JMS_TEST_SERVER=bastion go test ./...

Architecture, the reverse-engineered KoKo protocol details, pool design and failure-handling rules live in DESIGN.md (written in Chinese).

Releases are cut from GitHub Actions:

gh workflow run release --repo MiFaZhan/jms-client -f tag=v0.1.7

License

MIT © MiFaZhan. See LICENSE.

The design and the KoKo protocol findings build on GCS-ZHN/jms-cli.