SSH Nexus MCP

SSH Nexus is a local-first dashboard and Model Context Protocol (MCP) server for an existing OpenSSH inventory. It reads explicit aliases from ~/.ssh/config, shows live reachability and Linux resource usage, opens an interactive browser terminal, indexes a project for agent context, and exposes the same safe operations to Codex, Claude, and other MCP clients.

What it includes

• OpenSSH inventory with Host, Include, effective hostname, user, port, and ProxyJump support

• Structured dashboard add/edit using a separate managed SSH config with atomic backups

• Green/red reachability status with text labels and connection latency

• Interactive xterm.js terminal backed by the local ssh executable

• CPU, RAM, root-disk, load, uptime, and disk-I/O metrics over authenticated SSH

• Provider-neutral MCP tools, resources, and prompts for Codex, Claude Code, Claude Desktop, and compatible clients

• Bounded project indexing and text search for other AI agents

• Local-only binding by default, optional bearer authentication, alias allowlisting, and no private keys in the browser

• Non-overlapping fleet refreshes capped at eight concurrent host probes

• Responsive, keyboard-accessible dashboard

Related MCP server: mcp-ssh-fleet

Requirements

• Node.js 22 or newer

• npm 10 or newer

• OpenSSH client (ssh in PATH)

• A working ~/.ssh/config

• Key-based/non-interactive SSH authentication for automatic metrics

• Linux remote hosts for the full metrics set (non-Linux hosts show the fields they support)

Quick start

git clone https://github.com/YOUR_USERNAME/ssh-nexus-mcp.git
cd ssh-nexus-mcp
npm install
cp .env.example .env
npm run dev

Open http://127.0.0.1:5173. Vite serves the development UI and proxies the API/WebSocket to port 3100.

For a production-style local run:

npm run build
npm start

Open http://127.0.0.1:3100.

The default configuration already reads ~/.ssh/config. A minimal SSH entry looks like:

Host production-web
    HostName 203.0.113.10
    User deploy
    Port 22
    IdentityFile ~/.ssh/id_ed25519

SSH Nexus lists explicit aliases only. Wildcard blocks such as Host * contribute OpenSSH defaults but do not become dashboard cards.

Managed server editing

Dashboard editing is disabled by default. It never rewrites ~/.ssh/config; changes go to SSH_NEXUS_MANAGED_CONFIG (default ~/.ssh/ssh-nexus/hosts.conf) and the previous managed file is backed up as hosts.conf.bak.

Enable editing with a bearer token:

export SSH_NEXUS_TOKEN="$(openssl rand -hex 32)"
export ALLOW_SSH_CONFIG_WRITES=true
npm run dev

The editor supports alias, hostname/IP, user, port, and explicit ProxyJump aliases. Editing an existing source alias creates a managed override while leaving the original entry untouched. Private-key paths and arbitrary OpenSSH directives are intentionally not editable.

Connect an AI agent

Build the project first:

npm run build

Codex

codex mcp add ssh-nexus -- node "$(pwd)/dist/server/mcp-stdio.js"
codex mcp list

Codex also supports project-scoped .codex/config.toml:

[mcp_servers.ssh_nexus]
command = "node"
args = ["/absolute/path/to/ssh-nexus-mcp/dist/server/mcp-stdio.js"]
default_tools_approval_mode = "writes"

See the official Codex MCP documentation.

Claude Code

claude mcp add ssh-nexus -- node "$(pwd)/dist/server/mcp-stdio.js"
claude mcp get ssh-nexus

Use --scope user before -- if you want the integration in all projects. See the official Claude Code MCP documentation.

Claude Desktop or another MCP host

Add this stdio definition, replacing the absolute path:

{
  "mcpServers": {
    "ssh-nexus": {
      "command": "node",
      "args": ["/absolute/path/to/ssh-nexus-mcp/dist/server/mcp-stdio.js"]
    }
  }
}

The dashboard's Connect AI dialog generates copy-ready commands using the current project path.

Streamable HTTP

While the dashboard is running, MCP is also available at:

http://127.0.0.1:3100/mcp

If SSH_NEXUS_TOKEN is set, clients must send Authorization: Bearer <token>. Do not expose this endpoint publicly without TLS and a proper identity-aware proxy.

MCP capabilities

To deliberately enable arbitrary MCP remote commands:

ALLOW_REMOTE_COMMANDS=true npm start

This changes the trust boundary. Keep agent approval enabled and review commands before execution.

Project indexing

Press Build index in the dashboard or call refresh_project_index. The generated .ssh-nexus/index.json contains paths, sizes, line counts, modification times, SHA-256 hashes, and language counts. It does not copy file content into the index.

The indexer skips .git, dependencies, build output, its own generated directory, symlinks, .env*, private-key-style names, and common certificate/keystore extensions. Allowed roots are controlled by PROJECT_ROOTS.

Configuration

The dashboard never reads private-key content. OpenSSH itself resolves identities, agents, proxies, host keys, and authentication.

Docker

Native installation is recommended because it naturally uses your SSH agent and filesystem permissions. For Docker:

export SSH_NEXUS_TOKEN="$(openssl rand -hex 32)"
export ALLOW_SSH_CONFIG_WRITES=true
docker compose up --build

The browser asks for this token. Compose mounts ${HOME}/.ssh read-only, keeps managed entries in the persistent ssh-nexus-data volume, and leaves config editing disabled unless ALLOW_SSH_CONFIG_WRITES=true. The repository is mounted at /workspace. On Linux, make sure mounted key files are readable by the container's node user and that host keys are already present in known_hosts.

Validate before pushing

npm run check

Then create and push your GitHub repository:

git init
git add .
git commit -m "feat: initial SSH Nexus MCP dashboard"
gh repo create ssh-nexus-mcp --source=. --private --push

Change --private to --public only after reviewing the repository for personal hostnames or local configuration. SSH Nexus does not commit your SSH config or generated index.

Documentation

• Installation and operations

• Architecture

• Security model

• AI agent integration

• HTTP and WebSocket API

• Project map

• Contributing

License

MIT