ssh_run
Execute remote commands over SSH to run non-interactive operations on servers and retrieve output, exit codes, and error messages for remote administration tasks.
Instructions
Runs a non-interactive command remotely over SSH and returns stdout, stderr, and exit code
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Command to run remotely |
Implementation Reference
- src/index.ts:118-137 (handler)The main handler function for the 'ssh_run' tool. It establishes an SSH connection using environment variables, executes the provided command, captures stdout/stderr/exit code, formats the result as JSON, and handles errors.async ({ command }) => { try { const ssh = await createSshConnection(); try { const result = await runRemoteCommand(ssh, command); ssh.end(); const text = JSON.stringify( { command, ...result, stdout: result.stdout.trim(), stderr: result.stderr.trim() }, null, 2 ); return { content: [{ type: "text", text }] }; } finally { ssh.end(); } } catch (error) { const message = error instanceof Error ? error.message : String(error); return { content: [{ type: "text", text: `SSH command failed: ${message}` }], isError: true }; } }
- src/index.ts:113-117 (schema)Input schema for the 'ssh_run' tool, defining a required 'command' parameter as a non-empty string.{ title: "Run Remote Command", description: "Runs a non-interactive command remotely over SSH and returns stdout, stderr, and exit code", inputSchema: { command: z.string().min(1).describe("Command to run remotely") }, },
- src/index.ts:111-138 (registration)Registration of the 'ssh_run' tool with the MCP server, including schema and handler.server.registerTool( "ssh_run", { title: "Run Remote Command", description: "Runs a non-interactive command remotely over SSH and returns stdout, stderr, and exit code", inputSchema: { command: z.string().min(1).describe("Command to run remotely") }, }, async ({ command }) => { try { const ssh = await createSshConnection(); try { const result = await runRemoteCommand(ssh, command); ssh.end(); const text = JSON.stringify( { command, ...result, stdout: result.stdout.trim(), stderr: result.stderr.trim() }, null, 2 ); return { content: [{ type: "text", text }] }; } finally { ssh.end(); } } catch (error) { const message = error instanceof Error ? error.message : String(error); return { content: [{ type: "text", text: `SSH command failed: ${message}` }], isError: true }; } } );
- src/index.ts:55-73 (helper)Helper function to execute a remote command over an established SSH connection and return stdout, stderr, and exit code.async function runRemoteCommand(ssh: SSHClient, command: string): Promise<{ exitCode: number; stdout: string; stderr: string }>{ return await new Promise((resolve, reject) => { ssh.exec(command, (err: Error | undefined, stream: ClientChannel) => { if (err) return reject(err); let stdout = ""; let stderr = ""; stream .on("close", (code: number) => { resolve({ exitCode: code ?? 0, stdout, stderr }); }) .on("data", (data: Buffer) => { stdout += data.toString(); }) .stderr.on("data", (data: Buffer) => { stderr += data.toString(); }); }); }); }
- src/index.ts:32-53 (helper)Helper function to create and connect an SSH client using environment variables SSH_HOST, SSH_PORT, SSH_USERNAME, SSH_PASSWORD.async function createSshConnection(): Promise<SSHClient> { const env = getEnv(); const ssh = new SSHClient(); const config: ConnectConfig = { host: env.SSH_HOST, port: Number(env.SSH_PORT), username: env.SSH_USERNAME, password: env.SSH_PASSWORD, readyTimeout: 15000, tryKeyboard: false, algorithms: { // Keep defaults; allow host key algo negotiation modern-first }, }; await new Promise<void>((resolve, reject) => { ssh .on("ready", () => resolve()) .on("error", (err: Error) => reject(err)) .connect(config); }); return ssh; }