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.
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
mcpb https://github.com/MiFaZhan/jms-client/releases/download/v0.2.4/jms-client.mcpbClaude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add mifazhan-jms-client -- mcpb https://github.com/MiFaZhan/jms-client/releases/download/v0.2.4/jms-client.mcpb在終端機中執行。
{ "mcpServers": { "mifazhan-jms-client": { "command": "mcpb", "args": [ "https://github.com/MiFaZhan/jms-client/releases/download/v0.2.4/jms-client.mcpb" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
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.
JumpServer v4 bastion CLI and MCP server in Go: pooled connections, endpoint failover, SFTP transfers, interactive login
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
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:
2222) to be open on the network path — many deployments only expose the web port, so check before relying on them.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 bucket add mifazhan https://github.com/MiFaZhan/scoop-bucket
scoop install jms-client
Upgrade later with scoop update jms-client.
Requires Go 1.25 or newer:
go install github.com/MiFaZhan/jms-client/cmd/jms@latest
git clone https://github.com/MiFaZhan/jms-client
cd jms-client
go build -o jms ./cmd/jms
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.
$ 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.
$ 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.
$ 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
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"
}
}
}
}
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:
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).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.Target syntax is <asset>@<server>; omitting @<server> uses the default server.
Full reference: docs/command-reference.md · 简体中文
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 · 简体中文
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.
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.
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.
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.When something goes wrong: docs/troubleshooting.md · 简体中文
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
MIT © MiFaZhan. See LICENSE.
The design and the KoKo protocol findings build on GCS-ZHN/jms-cli.
JumpServer v4 bastion CLI and MCP server in Go: pooled connections, endpoint failover, SFTP transfers, interactive login
{ "mcpServers": { "mifazhan-jms-client": { "command": "mcpb", "args": [ "https://github.com/MiFaZhan/jms-client/releases/download/v0.2.4/jms-client.mcpb" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Jms Client 透過 stdio 在本機執行。
上次檢查時間:2026-10-28。 JumpServer v4 bastion CLI and MCP server in Go: pooled connections, endpoint failover, SFTP transfers, interactive login