SSH MCP Server

Instructions

Implementation Reference

• src/index.ts:566-635 (handler)

  The `handleShellStart` method implements the `ssh_shell_start` tool by creating an interactive SSH shell session with a pseudo-terminal (PTY).

  private async handleShellStart(args: any): Promise<CallToolResult> {
    this.requireConnection();
  
    if (this.shellSessions.size >= SSHMCPServer.MAX_SESSIONS) {
      throw new Error(
        `Máximo de ${SSHMCPServer.MAX_SESSIONS} sesiones concurrentes alcanzado. Cierra una sesión existente primero.`
      );
    }
  
    const cols = (args?.cols as number) || 80;
    const rows = (args?.rows as number) || 24;
  
    return new Promise<CallToolResult>((resolve, reject) => {
      this.sshClient!.shell({ cols, rows, term: "xterm" }, (err, stream) => {
        if (err) {
          this.audit("ssh_shell_start", "", "error");
          reject(new Error(`Error iniciando shell: ${err.message}`));
          return;
        }
  
        const sessionId = `shell-${++this.sessionCounter}`;
        const session: ShellSession = {
          id: sessionId,
          channel: stream,
          buffer: "",
          createdAt: new Date(),
          lastActivity: new Date(),
          idleTimer: this.createIdleTimer(sessionId),
        };
  
        stream.on("data", (data: Buffer) => {
          session.buffer += data.toString();
          // Truncar buffer si excede el máximo
          if (session.buffer.length > SSHMCPServer.MAX_BUFFER) {
            session.buffer = session.buffer.slice(-SSHMCPServer.MAX_BUFFER);
          }
          session.lastActivity = new Date();
        });
  
        stream.on("close", () => {
          if (this.shellSessions.has(sessionId)) {
            this.destroyShellSession(sessionId, session);
            this.audit("ssh_shell_close", `sessionId=${sessionId} (channel closed)`, "ok");
          }
        });
  
        this.shellSessions.set(sessionId, session);
        this.audit("ssh_shell_start", `sessionId=${sessionId}`, "ok");
  
        // Esperar el banner/prompt inicial
        setTimeout(() => {
          resolve({
            content: [
              {
                type: "text",
                text: [
                  `Sesión de shell iniciada: ${sessionId}`,
                  `Terminal: ${cols}x${rows}`,
                  `Auto-cierre por inactividad: 5 minutos`,
                  ``,
                  `Output inicial:`,
                  stripAnsi(session.buffer) || "(esperando output...)",
                ].join("\n"),
              },
            ],
          });
        }, SSHMCPServer.SETTLE_TIMEOUT);
      });
    });
  }

• src/tools.ts:192-208 (schema)

  Definition and schema for the `ssh_shell_start` tool.

    name: "ssh_shell_start",
    description:
      "Inicia una sesión de shell interactiva persistente con PTY. Útil para REPLs, workflows multi-paso, o login a servicios. Máximo 5 sesiones concurrentes. Auto-cierre tras 5 min de inactividad",
    inputSchema: {
      type: "object",
      properties: {
        cols: {
          type: "number",
          description: "Ancho del terminal en columnas (default: 80)",
        },
        rows: {
          type: "number",
          description: "Alto del terminal en filas (default: 24)",
        },
      },
    },
  },

• src/index.ts:79-80 (registration)

  Registration of the `ssh_shell_start` tool in the request handler switch case.

  case "ssh_shell_start":
    return await this.handleShellStart(args);