execute_command
Execute system commands locally or on remote hosts via SSH using the Terminal MCP Server. Supports persistent sessions and environment variables for consistent terminal environments.
Instructions
Execute commands on remote hosts or locally (This tool can be used for both remote hosts and the current machine)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Command to execute. Before running commands, it's best to determine the system type (Mac, Linux, etc.) | |
| env | No | Environment variables | |
| host | No | Host to connect to (optional, if not provided the command will be executed locally) | |
| session | No | Session name, defaults to 'default'. The same session name will reuse the same terminal environment for 20 minutes, which is useful for operations requiring specific environments like conda. | default |
| username | No | Username for SSH connection (required when host is specified) |
Implementation Reference
- src/executor.ts:138-357 (handler)Core handler function that executes the command either locally using child_process.exec or remotely via SSH2 with advanced session management, interactive shell support, environment variable persistence across calls in the same session, and timeout handling.
async executeCommand( command: string, options: { host?: string; username?: string; session?: string; env?: Record<string, string>; } = {} ): Promise<{stdout: string; stderr: string}> { const { host, username, session = 'default', env = {} } = options; const sessionKey = this.getSessionKey(host, session); // 如果指定了host，则使用SSH执行命令 if (host) { if (!username) { throw new Error('Username is required when using SSH'); } let sessionData = this.sessions.get(sessionKey); // 检查会话是否存在且有效 let needNewConnection = false; if (!sessionData || sessionData.host !== host) { needNewConnection = true; } else if (sessionData.client) { // 检查客户端是否仍然连接 if (sessionData.client.listenerCount('ready') === 0 && sessionData.client.listenerCount('data') === 0) { log.info(`Session ${sessionKey} disconnected, reconnecting`); needNewConnection = true; } } else { needNewConnection = true; } // 如果需要新连接，则创建 if (needNewConnection) { log.info(`Creating new connection for command execution: ${sessionKey}`); await this.connect(host, username, session); sessionData = this.sessions.get(sessionKey); } else { log.info(`Reusing existing session for command execution: ${sessionKey}`); } if (!sessionData || !sessionData.client) { throw new Error(`无法创建到 ${host} 的SSH会话`); } this.resetTimeout(sessionKey); // 检查是否有交互式shell可用 if (sessionData.shellReady && sessionData.shell) { log.info(`Executing command using interactive shell: ${command}`); return new Promise((resolve, reject) => { let stdout = ""; let stderr = ""; let commandFinished = false; const uniqueMarker = `CMD_END_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`; // 构建环境变量设置命令 const envSetup = Object.entries(env) .map(([key, value]) => `export ${key}="${String(value).replace(/"/g, '\\"')}"`) .join(' && '); // 如果有环境变量，先设置环境变量，再执行命令 const fullCommand = envSetup ? `${envSetup} && ${command}` : command; // 添加数据处理器 const dataHandler = (data: Buffer) => { const str = data.toString(); log.debug(`Shell数据: ${str}`); if (str.includes(uniqueMarker)) { // 命令执行完成 commandFinished = true; // 提取命令输出（从命令开始到标记之前的内容） const lines = stdout.split('\n'); let commandOutput = ''; let foundCommand = false; for (const line of lines) { if (foundCommand) { if (line.includes(uniqueMarker)) { break; } commandOutput += line + '\n'; } else if (line.includes(fullCommand)) { foundCommand = true; } } // 解析输出 resolve({ stdout: commandOutput.trim(), stderr }); // 移除处理器 sessionData.shell.removeListener('data', dataHandler); clearTimeout(timeout); } else if (!commandFinished) { stdout += str; } }; // 添加错误处理器 const errorHandler = (err: Error) => { stderr += err.message; reject(err); sessionData.shell.removeListener('data', dataHandler); sessionData.shell.removeListener('error', errorHandler); }; // 监听数据和错误 sessionData.shell.on('data', dataHandler); sessionData.shell.on('error', errorHandler); // 执行命令并添加唯一标记 // 使用一个更明确的方式来执行命令和捕获输出 sessionData.shell.write(`echo "Starting command execution: ${fullCommand}"\n`); sessionData.shell.write(`${fullCommand}\n`); sessionData.shell.write(`echo "${uniqueMarker}"\n`); // 设置超时 const timeout = setTimeout(() => { if (!commandFinished) { stderr += "Command execution timed out"; resolve({ stdout, stderr }); sessionData.shell.removeListener('data', dataHandler); sessionData.shell.removeListener('error', errorHandler); } }, 30000); // 30秒超时 }); } else { log.info(`Executing command using exec: ${command}`); return new Promise((resolve, reject) => { // 构建环境变量设置命令 const envSetup = Object.entries(env) .map(([key, value]) => `export ${key}="${String(value).replace(/"/g, '\\"')}"`) .join(' && '); // 如果有环境变量，先设置环境变量，再执行命令 const fullCommand = envSetup ? `${envSetup} && ${command}` : command; sessionData?.client?.exec(`/bin/bash --login -c "${fullCommand.replace(/"/g, '\\"')}"`, (err, stream) => { if (err) { reject(err); return; } let stdout = ""; let stderr = ''; stream .on("data", (data: Buffer) => { this.resetTimeout(sessionKey); stdout += data.toString(); }) .stderr.on('data', (data: Buffer) => { stderr += data.toString(); }) .on('close', () => { resolve({ stdout, stderr }); }) .on('error', (err) => { reject(err); }); }); }); } } // 否则在本地执行命令 else { // 在本地执行命令时，也使用会话机制来保持环境变量 log.info(`Executing command using local session: ${sessionKey}`); // 检查是否已有本地会话 let sessionData = this.sessions.get(sessionKey); let sessionEnv = {}; if (!sessionData) { // 为本地会话创建一个空条目，以便跟踪超时 sessionData = { client: null, connection: null, timeout: null, host: undefined, env: { ...env } // 保存初始环境变量 }; this.sessions.set(sessionKey, sessionData); log.info(`Creating new local session: ${sessionKey}`); sessionEnv = env; } else { log.info(`Reusing existing local session: ${sessionKey}`); // 合并现有会话环境变量和新的环境变量 if (!sessionData.env) { sessionData.env = {}; } sessionData.env = { ...sessionData.env, ...env }; sessionEnv = sessionData.env; // 更新会话 this.sessions.set(sessionKey, sessionData); } this.resetTimeout(sessionKey); return new Promise((resolve, reject) => { // 构建环境变量，优先级：系统环境变量 < 会话环境变量 < 当前命令环境变量 const envVars = { ...process.env, ...sessionEnv }; // 执行命令 log.info(`Executing local command: ${command}`); exec(command, { env: envVars }, (error, stdout, stderr) => { if (error && error.code !== 0) { // 我们不直接拒绝，而是返回错误信息作为stderr resolve({ stdout, stderr: stderr || error.message }); } else { resolve({ stdout, stderr }); } }); }); } } - src/index.ts:50-82 (schema)Input schema and description for the 'execute_command' tool, provided in the ListTools response.
{ name: "execute_command", description: "Execute commands on remote hosts or locally (This tool can be used for both remote hosts and the current machine)", inputSchema: { type: "object", properties: { host: { type: "string", description: "Host to connect to (optional, if not provided the command will be executed locally)" }, username: { type: "string", description: "Username for SSH connection (required when host is specified)" }, session: { type: "string", description: "Session name, defaults to 'default'. The same session name will reuse the same terminal environment for 20 minutes, which is useful for operations requiring specific environments like conda.", default: "default" }, command: { type: "string", description: "Command to execute. Before running commands, it's best to determine the system type (Mac, Linux, etc.)" }, env: { type: "object", description: "Environment variables", default: {} } }, required: ["command"] } } ] - src/index.ts:47-84 (registration)Registration of the 'execute_command' tool via the ListToolsRequestSchema handler, listing the tool with its schema.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "execute_command", description: "Execute commands on remote hosts or locally (This tool can be used for both remote hosts and the current machine)", inputSchema: { type: "object", properties: { host: { type: "string", description: "Host to connect to (optional, if not provided the command will be executed locally)" }, username: { type: "string", description: "Username for SSH connection (required when host is specified)" }, session: { type: "string", description: "Session name, defaults to 'default'. The same session name will reuse the same terminal environment for 20 minutes, which is useful for operations requiring specific environments like conda.", default: "default" }, command: { type: "string", description: "Command to execute. Before running commands, it's best to determine the system type (Mac, Linux, etc.)" }, env: { type: "object", description: "Environment variables", default: {} } }, required: ["command"] } } ] }; }); - src/index.ts:86-138 (handler)MCP CallTool request handler specifically for the 'execute_command' tool, which parses input, validates, calls CommandExecutor.executeCommand, and formats the response.
server.setRequestHandler(CallToolRequestSchema, async (request) => { try { if (request.params.name !== "execute_command") { throw new McpError(ErrorCode.MethodNotFound, "Unknown tool"); } const host = request.params.arguments?.host ? String(request.params.arguments.host) : undefined; const username = request.params.arguments?.username ? String(request.params.arguments.username) : undefined; const session = String(request.params.arguments?.session || "default"); const command = String(request.params.arguments?.command); if (!command) { throw new McpError(ErrorCode.InvalidParams, "Command is required"); } const env = request.params.arguments?.env || {}; // 如果指定了host但没有指定username if (host && !username) { throw new McpError(ErrorCode.InvalidParams, "Username is required when host is specified"); } try { const result = await commandExecutor.executeCommand(command, { host, username, session, env: env as Record<string, string> }); return { content: [{ type: "text", text: `Command Output:\nstdout: ${result.stdout}\nstderr: ${result.stderr}` }] }; } catch (error) { if (error instanceof Error && error.message.includes('SSH')) { throw new McpError( ErrorCode.InternalError, `SSH connection error: ${error.message}. Please ensure SSH key-based authentication is set up.` ); } throw error; } } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, error instanceof Error ? error.message : String(error) ); } });