Run Remote Command
ssh_runExecute remote commands on servers via SSH to run non-interactive tasks and retrieve execution results including output, errors, and status codes.
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, executes the provided command using runRemoteCommand, formats the output 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:116-116 (schema)Input schema for the 'ssh_run' tool defining the 'command' parameter using Zod.
inputSchema: { command: z.string().min(1).describe("Command to run remotely") }, - src/index.ts:111-138 (registration)Registration of the 'ssh_run' tool on the McpServer instance, 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 command over an established SSH connection and capture 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.
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; }