Terminal MCP

Instructions

The input is sent to the visible terminal window and executed there.
The user can see the command being executed in real-time.

Args:
    session_id: The terminal session ID returned by terminal_create_or_get.
    text: The text/command to send. This will be executed as a shell command.

Returns:
    dict: Contains success status, session_id, and the sent text.

Examples:
    - Run a command: terminal_send_input(session_id="abc123", text="ls -la")
    - Start a server: terminal_send_input(session_id="abc123", text="npm start")
    - Run Python: terminal_send_input(session_id="abc123", text="python script.py")

Note:
    The command is executed asynchronously. Use terminal_get_output to
    retrieve the results after the command completes.

Implementation Reference

• src/terminal_mcp/server.py:73-118 (handler)

  The implementation of the terminal_send_input tool handler. It validates the session and delegates to the session manager.

  async def terminal_send_input(session_id: str, text: str) -> dict:
      """Send input (command or text) to a terminal.
  
      The input is sent to the visible terminal window and executed there.
      The user can see the command being executed in real-time.
  
      Args:
          session_id: The terminal session ID returned by terminal_create_or_get.
          text: The text/command to send. This will be executed as a shell command.
  
      Returns:
          dict: Contains success status, session_id, and the sent text.
  
      Examples:
          - Run a command: terminal_send_input(session_id="abc123", text="ls -la")
          - Start a server: terminal_send_input(session_id="abc123", text="npm start")
          - Run Python: terminal_send_input(session_id="abc123", text="python script.py")
  
      Note:
          The command is executed asynchronously. Use terminal_get_output to
          retrieve the results after the command completes.
      """
      manager = SessionManager.get_instance()
      session = await manager.get_session(session_id)
  
      if not session:
          return {
              "success": False,
              "error": f"Session '{session_id}' not found. It may have been closed or never existed.",
              "suggestion": "Use terminal_create_or_get to create a new terminal.",
          }
  
      success = await manager.send_input(session_id, text)
      if success:
          return {
              "success": True,
              "session_id": session_id,
              "sent_text": text,
              "message": f"Command sent to terminal '{session.name}'",
          }
      else:
          return {
              "success": False,
              "session_id": session_id,
              "error": "Failed to send input. The terminal may have been closed.",
          }

• src/terminal_mcp/server.py:63-72 (registration)

  The tool registration using the @mcp.tool decorator.

  @mcp.tool(
      name="terminal_send_input",
      annotations={
          "title": "Send Input to Terminal",
          "readOnlyHint": False,
          "destructiveHint": True,
          "idempotentHint": False,
          "openWorldHint": True,
      },
  )