SSH MCP Server

Instructions

Implementation Reference

• src/index.ts:120-168 (handler)

  The core handler function that creates an SSH client connection using ssh2, executes the provided command, captures stdout, stderr, and exit code, and resolves with SSHCommandResult.

  private executeSSHCommand(
    config: SSHConnectionConfig,
    command: string
  ): Promise<SSHCommandResult> {
    return new Promise((resolve, reject) => {
      const conn = new Client();
      let stdout = '';
      let stderr = '';
      let code: number | null = null;
  
      conn.on('ready', () => {
        conn.exec(command, (err, stream) => {
          if (err) {
            conn.end();
            return reject(err);
          }
  
          stream
            .on('close', (exitCode: number) => {
              code = exitCode;
              conn.end();
              resolve({ stdout, stderr, code });
            })
            .on('data', (data: string) => {
              stdout += data;
            })
            .stderr.on('data', (data: string) => {
              stderr += data;
            });
        });
      }).on('error', (err) => {
        reject(err);
      });
  
      const connectOptions: any = {
        host: config.host,
        port: config.port || 22,
        username: config.username,
      };
  
      if (config.password) {
        connectOptions.password = config.password;
      } else if (config.privateKey) {
        connectOptions.privateKey = config.privateKey;
      }
  
      conn.connect(connectOptions);
    });
  }

• src/index.ts:74-117 (handler)

  The MCP CallTool request handler that validates the tool name 'execute_ssh_command', extracts arguments, calls executeSSHCommand, and formats the response content based on success or failure.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name !== 'execute_ssh_command') {
      throw new McpError(
        ErrorCode.MethodNotFound,
        `Unknown tool: ${request.params.name}`
      );
    }
  
    if (!request.params.arguments) {
      throw new McpError(ErrorCode.InvalidParams, 'Missing arguments');
    }
    
    const { connection, command } = request.params.arguments as {
      connection: SSHConnectionConfig;
      command: string;
    };
    
    if (!connection || !command) {
      throw new McpError(ErrorCode.InvalidParams, 'Missing connection or command');
    }
    
    const result = await this.executeSSHCommand(connection, command);
  
    if (result.code !== 0) {
      return {
        content: [
          {
            type: 'text',
            text: `Command failed with code ${result.code}\nSTDERR: ${result.stderr}`,
          },
        ],
        isError: true,
      };
    }
  
    return {
      content: [
        {
          type: 'text',
          text: result.stdout,
        },
      ],
    };
  });

• src/index.ts:49-70 (schema)

  The tool definition including name, description, and detailed inputSchema for SSH connection configuration and command.

  {
    name: 'execute_ssh_command',
    description: 'Execute command on remote server via SSH',
    inputSchema: {
      type: 'object',
      properties: {
        connection: {
          type: 'object',
          properties: {
            host: { type: 'string' },
            port: { type: 'number', default: 22 },
            username: { type: 'string' },
            password: { type: 'string' },
            privateKey: { type: 'string' },
          },
          required: ['host', 'username'],
        },
        command: { type: 'string' },
      },
      required: ['connection', 'command'],
    },
  },

• src/index.ts:47-72 (registration)

  Registers the 'execute_ssh_command' tool by handling ListToolsRequestSchema and returning the tool list.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'execute_ssh_command',
        description: 'Execute command on remote server via SSH',
        inputSchema: {
          type: 'object',
          properties: {
            connection: {
              type: 'object',
              properties: {
                host: { type: 'string' },
                port: { type: 'number', default: 22 },
                username: { type: 'string' },
                password: { type: 'string' },
                privateKey: { type: 'string' },
              },
              required: ['host', 'username'],
            },
            command: { type: 'string' },
          },
          required: ['connection', 'command'],
        },
      },
    ],
  }));

• src/index.ts:20-24 (schema)

  TypeScript interface defining the structure of the SSH command execution result.

  interface SSHCommandResult {
    stdout: string;
    stderr: string;
    code: number | null;
  }

• src/index.ts:12-18 (schema)

  TypeScript interface defining the SSH connection configuration.

  interface SSHConnectionConfig {
    host: string;
    port?: number;
    username: string;
    password?: string;
    privateKey?: string;
  }