terminal_create_or_get

Create new terminal windows or access existing ones by name for direct user interaction and command execution. Specify a working directory to control where commands run.

Instructions

Create a new visible terminal window or get an existing one by name.

The terminal opens in a visible window that the user can interact with directly.
Commands sent to this terminal will be executed in that visible window.

Args:
    name: Optional name for the terminal. If a terminal with this name
          already exists and is still alive, it will be returned instead
          of creating a new one.
    working_dir: Optional working directory for the terminal.
                 If not specified, uses the current working directory.

Returns:
    dict: Contains session_id, name, platform, and a status message.
          Use the session_id for subsequent operations.

Examples:
    - Create unnamed terminal: terminal_create_or_get()
    - Create named terminal: terminal_create_or_get(name="dev-server")
    - Get existing terminal: terminal_create_or_get(name="dev-server")

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	No
`working_dir`	No

Implementation Reference

src/terminal_mcp/server.py:25-60 (handler)

The handler function for 'terminal_create_or_get' which triggers session creation via the SessionManager.

async def terminal_create_or_get(
    name: Optional[str] = None, working_dir: Optional[str] = None
) -> dict:
    """Create a new visible terminal window or get an existing one by name.

    The terminal opens in a visible window that the user can interact with directly.
    Commands sent to this terminal will be executed in that visible window.

    Args:
        name: Optional name for the terminal. If a terminal with this name
              already exists and is still alive, it will be returned instead
              of creating a new one.
        working_dir: Optional working directory for the terminal.
                     If not specified, uses the current working directory.

    Returns:
        dict: Contains session_id, name, platform, and a status message.
              Use the session_id for subsequent operations.

    Examples:
        - Create unnamed terminal: terminal_create_or_get()
        - Create named terminal: terminal_create_or_get(name="dev-server")
        - Get existing terminal: terminal_create_or_get(name="dev-server")
    """
    manager = SessionManager.get_instance()
    session = await manager.create_or_get_terminal(name, working_dir)
    web_url = get_web_url(session.id)
    session.web_url = web_url
    webbrowser.open(web_url)
    return {
        "session_id": session.id,
        "name": session.name,
        "platform": session.platform,
        "web_url": web_url,
        "message": f"Terminal '{session.name}' is ready (session: {session.id})",
    }

src/terminal_mcp/server.py:15-24 (registration)

Registration of 'terminal_create_or_get' using the @mcp.tool decorator.

@mcp.tool(
    name="terminal_create_or_get",
    annotations={
        "title": "Create or Get Terminal",
        "readOnlyHint": False,
        "destructiveHint": False,
        "idempotentHint": True,
        "openWorldHint": True,
    },
)

src/terminal_mcp/session_manager.py:93-115 (helper)

The logic in SessionManager that handles creating or retrieving an existing terminal session.

async def create_or_get_terminal(
    self, name: Optional[str] = None, working_dir: Optional[str] = None
) -> TerminalSession:
    """Create a new terminal or get an existing one by name.

    Args:
        name: Optional terminal name. If specified and exists, returns existing session.
        working_dir: Optional working directory for the terminal.

    Returns:
        TerminalSession for the created or existing terminal.
    """
    async with self._lock:
        # If name specified, try to find existing session
        if name:
            for session in self._sessions.values():
                if session.name == name:
                    if await self._terminal.is_session_alive(session):
                        return session
                    else:
                        # Clean up dead session
                        await self._terminal.close_terminal(session)
                        del self._sessions[session.id]

Terminal MCP