Skip to main content
Glama

nomad

中文说明

nomad is a local MCP server for agentic remote development. It keeps source code local while an AI agent syncs with rsync, runs commands over SSH, manages long jobs in remote tmux, and pulls artifacts back into the project.

For Codex, use the project-scoped Streamable HTTP daemon. Stdio remains available for compatible clients and one-off use.

Features

  • Multiple remote targets per local project.

  • Project-local .nomad.json configuration.

  • SSH preflight checks and read-only network diagnostics.

  • Incremental rsync push and guarded artifact pull.

  • Short remote commands and long-running tmux tasks.

  • Optional persistent reverse SSH tunnels.

  • Path guards, dangerous-command checks, output limits, and secret redaction.

Related MCP server: ssh-mcp

Requirements

  • Python 3.11+, ssh, and rsync

  • Key-based SSH access to remote targets

  • Remote tmux when using long-running tasks

Daemon lifecycle management supports macOS, Linux, and other POSIX systems. Windows is not currently supported or tested.

Installation

Run the latest PyPI release without installing it globally:

uvx --from nomad-mcp nomad

Or install an isolated global command:

pipx install nomad-mcp

Codex Setup

nomad codex setup is an optional Codex configuration adapter, not a protocol requirement. Any MCP host can use Nomad through the standard stdio or Streamable HTTP transports without Codex configuration.

From the project you want Codex to control, run:

nomad codex setup --project "$PWD"
nomad codex doctor --project "$PWD"

The adapter starts or repairs a project daemon and writes only the trusted project's .codex/config.toml. It never changes user-level Codex configuration or project trust. Resolve any reported global conflict, then fully restart Codex so it loads the project MCP entry.

Other MCP hosts can launch Nomad directly over stdio:

{
  "mcpServers": {
    "nomad": {
      "command": "uvx",
      "args": ["--from", "nomad-mcp", "nomad"]
    }
  }
}

Use nomad client-config to generate JSON or TOML for standard stdio or Streamable HTTP clients. See Persistent MCP Daemon for manual registration, lifecycle, security, and troubleshooting.

Quick Start

  1. Start and register the project daemon.

  2. Open Codex in the local project.

  3. Call health, then init_discover.

  4. Select an SSH target and remote workspace.

  5. Save .nomad.json with init_save_config.

  6. Push code with sync_push.

  7. Use run_remote for short commands.

  8. Use task_start and task_status for long jobs.

  9. Pull artifacts with sync_pull.

Use run_remote only for short synchronous work. Downloads, builds, training, servers, and batch jobs belong in task_start. If a call with side effects times out, inspect its status before retrying it.

Documentation

Safety

nomad executes commands over SSH and synchronizes files with rsync. Use it only with trusted local projects and remote machines. Its guardrails reduce risk, but cannot make an untrusted agent or host trustworthy.

Development

python -m pip install -e .[dev]
nomad doctor
python -m pytest
python -m compileall -q src tests

License

MIT

Available Tools

15 tools
init_discoverA

Pre-scan local workspace environment, .ssh/config aliases and local proxies.

Inputs: no named parameters. Returns: result

init_probe_targetC

Refreshes hardware and runtime snapshot for the specified target.

Inputs: target. Returns: result

init_save_configC

Validates configuration parameters and saves them to .nomad.json.

Inputs: config_json (required). Returns: result

init_verify_and_probeC

Tests connection and probes target system specifications and runtimes.

Inputs: ssh_host (required), remote_path (required), jump_host. Returns: result

net_diagnoseC

Runs read-only SSH/network diagnostics for a configured target.

Inputs: target. Returns: result

run_remoteC

Executes a command on the remote host workspace under target limits.

Inputs: cmd (required), target. Returns: result

sync_pullC

Pulls a remote artifact into a local project-owned directory.

Inputs: remote_relative_path (required), target, local_dest. Returns: result

sync_pushC

Synchronizes local files to the remote workspace target.

Inputs: target. Returns: result

task_killA

Terminates an active tmux session for a task without removing logs/exits or stopping tunnel.

Inputs: task_name (required), target. Returns: result

task_listA

Lists long-running tasks for the given target, or all targets if None.

Inputs: target. Returns: result

task_startC

Starts an asynchronous task under tmux on the remote host.

Inputs: cmd (required), task_name (required), target. Returns: result

task_statusC

Checks the status and reads log tail of a tmux long-running task.

Inputs: task_name (required), target, tail_lines. Returns: result

tunnel_startC

Starts a persistent reverse SSH tunnel for the target.

Inputs: target. Returns: result

tunnel_statusC

Checks the status of the reverse tunnel for the target.

Inputs: target. Returns: result

tunnel_stopC

Stops the persistent reverse SSH tunnel for the target.

Inputs: target. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 15 tools

    Disambiguation5/5

    All tools have clearly distinct purposes organized by prefixes (init, net, run, sync, task, tunnel). No overlapping functionality exists.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case with logical prefixes, making them predictable and easy to understand.

    Tool Count5/5

    With 15 tools, the server is well-scoped for remote workspace management covering initialization, networking, execution, sync, tasks, and tunnels.

    Completeness5/5

    The tool surface provides comprehensive lifecycle coverage for tasks (start/list/status/kill) and tunnels (start/status/stop), plus init, sync, and diagnostics.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server for SSH and local terminal access. Supports interactive commands, long-running processes, and TUI apps like tmux/zellij
      6
      4
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that gives AI agents SSH access to remote machines through your local OpenSSH client, enabling remote command execution, file transfer, persistent shell sessions, and port forwarding.
      17
      275 PyPI
      40
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      A comprehensive MCP server for driving tmux sessions, windows, panes, sending keystrokes, and reading pane output locally or over SSH, enabling real-time collaborative pairing with AI.
      71
      29 PyPI
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      SSH orchestration MCP server for coding agents, enabling persistent bash sessions, hash-protected remote file editing, SFTP transfers, SSH tunnels, and multi-host orchestration with connection reuse across tools.
      14
      8
      Apache 2.0