execute_ssh_command
Execute commands on remote servers via SSH to manage systems, run scripts, or perform administrative tasks using persistent or new sessions.
Instructions
Execute a command on a remote server via SSH. Commands run in a persistent SSH session by default. Use newSession: true to run in a new session.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| port | No | ||
| username | Yes | ||
| password | No | ||
| privateKey | No | ||
| command | Yes | ||
| newSession | No |
Implementation Reference
- src/index.ts:18-26 (schema)Zod schema defining the input parameters for the execute_ssh_command tool, including host, port, username, authentication, command, and newSession option.const SSHConnectionArgsSchema = z.object({ host: z.string(), port: z.number().default(22), username: z.string(), password: z.string().optional(), privateKey: z.string().optional(), command: z.string(), newSession: z.boolean().optional(), });
- src/index.ts:71-156 (handler)The primary handler function that executes the SSH command. It uses the ssh2 Client to connect (reusing persistent connection if possible), runs the command, captures output and errors, and returns structured result with exit code.async function executeSSHCommand(config: z.infer<typeof SSHConnectionArgsSchema>): Promise<{ output: string, code: number }> { return new Promise((resolve) => { const useNewSession = config.newSession || false; // Check if we need a new session or if connection details changed if (!useNewSession && persistentSSH?.ready && persistentSSHConfig && persistentSSHConfig.host === config.host && persistentSSHConfig.port === config.port && persistentSSHConfig.username === config.username && persistentSSHConfig.password === config.password && persistentSSHConfig.privateKey === config.privateKey) { // Use existing connection persistentSSH.client.exec(config.command, (err: Error | undefined, stream: ClientChannel) => { if (err) { resolve({ output: `SSH exec error: ${err.message}`, code: 1 }); return; } let output = ''; let errorOutput = ''; stream.on('close', (code: number) => { resolve({ output: output + (errorOutput ? `\nErrors:\n${errorOutput}` : ''), code: code || 0 }); }).on('data', (data: Buffer) => { output += data.toString('utf8'); }).stderr.on('data', (data: Buffer) => { errorOutput += data.toString('utf8'); }); }); return; } // Need to create new connection const client = new Client(); const sshConfig = { host: config.host, port: config.port, username: config.username, ...(config.password ? { password: config.password } : {}), ...(config.privateKey ? { privateKey: config.privateKey } : {}), }; let output = ''; let errorOutput = ''; client.on('ready', () => { // If this is a persistent session, save the connection if (!useNewSession) { if (persistentSSH?.client) { persistentSSH.client.end(); } persistentSSH = { client, ready: true }; persistentSSHConfig = sshConfig; } client.exec(config.command, (err: Error | undefined, stream: ClientChannel) => { if (err) { resolve({ output: `SSH exec error: ${err.message}`, code: 1 }); if (useNewSession) client.end(); return; } stream.on('close', (code: number) => { resolve({ output: output + (errorOutput ? `\nErrors:\n${errorOutput}` : ''), code: code || 0 }); if (useNewSession) client.end(); }).on('data', (data: Buffer) => { output += data.toString('utf8'); }).stderr.on('data', (data: Buffer) => { errorOutput += data.toString('utf8'); }); }); }) .on('error', (err: Error) => { resolve({ output: `SSH connection error: ${err.message}`, code: 1 }); if (useNewSession) client.end(); }) .connect(sshConfig); }); }
- src/index.ts:169-175 (registration)Tool registration in the ListTools response, specifying name, description, and input schema derived from Zod.{ name: "execute_ssh_command", description: "Execute a command on a remote server via SSH. " + "Commands run in a persistent SSH session by default. " + "Use newSession: true to run in a new session.", inputSchema: zodToJsonSchema(SSHConnectionArgsSchema), },
- src/index.ts:302-316 (registration)Dispatch logic in the CallTool request handler that validates arguments using the schema and invokes the executeSSHCommand handler.} else if (name === "execute_ssh_command") { const parsed = SSHConnectionArgsSchema.safeParse(args); if (!parsed.success) { throw new Error(`Invalid arguments for execute_ssh_command: ${parsed.error}`); } const { output, code } = await executeSSHCommand(parsed.data); return { content: [{ type: "text", text: output || `Command completed with code ${code}` }], isError: code !== 0, }; }