terminal_create_or_get
Idempotent
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, }, ) - 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]