MCP Directory

How to add PiloTY to Claude Desktop

Persistent, interactive PTY terminal for AI agents over MCP — SSH, REPLs, password prompts, long-running jobs. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 38★ · stdio · no auth

Claude Desktop config for PiloTY

codex mcp add piloty -- uvx --from git+https://github.com/yiwenlu66/PiloTY.git piloty
{
  "mcpServers": {
    "piloty": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yiwenlu66/PiloTY.git",
        "piloty"
      ]
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

  1. 1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
  2. 2Paste the PiloTY config below under the top-level "mcpServers" key.
  3. 3Fill in any placeholder secrets (API keys, paths) in the snippet.
  4. 4Save the file, then fully quit and reopen Claude Desktop.
  5. 5Open a chat and confirm PiloTY's tools appear under the 🔌 tools menu.

Before you start

  • uv / uvx (Astral) to launch the server via `uvx`, or a local clone run with `uv --directory`
  • An MCP client that launches servers over stdio (e.g. Codex CLI, Claude)
  • Python (server is implemented in Python)

What PiloTY can do in Claude Desktop

send_line

Submit a newline-terminated command to the terminal session (drain-based).

send_text

Send raw bytes to the terminal without an appended newline (drain-based).

send_control

Send a control character (e.g. interrupt) to the foreground process (drain-based).

send_signal

Send a signal to the session's process (drain-based).

send_password

Enter a secret for a password prompt; suppresses transcript logging and terminal echo for that send (drain-based).

wait_for_output

Wait for new PTY output for a wall-clock budget; can return partial output with outcome=deadline_exceeded if output started but never went quiet.

wait_for_regex

Wait for content matching a regex; first checks already-rendered scrollback, then waits on new PTY bytes.

wait_for_shell_prompt

Wait for the shell prompt to return (e.g. after `ssh` or other login flows), consuming and returning the PTY output it waits on.

Security

PiloTY exposes unrestricted terminal access — treat it like giving the agent your keyboard. `send_password()` suppresses transcript logging and terminal echo for that send, but does not prevent other prompts or programs from echoing secrets later. Each server instance writes session logs (raw PTY bytes, inputs, captured output) under `~/.piloty/`, with server logs defaulting to `/tmp/piloty.log`.

PiloTY + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the PiloTY config there under the "mcpServers" key and restart the client.

Is PiloTY safe to use with Claude Desktop?

PiloTY exposes unrestricted terminal access — treat it like giving the agent your keyboard. `send_password()` suppresses transcript logging and terminal echo for that send, but does not prevent other prompts or programs from echoing secrets later. Each server instance writes session logs (raw PTY bytes, inputs, captured output) under `~/.piloty/`, with server logs defaulting to `/tmp/piloty.log`.

How does state persist between tool calls?

Each session is one real interactive terminal addressed by a `session_id` string. Reusing the same id keeps cwd, environment variables, the foreground process, remote SSH connections, and REPL/debugger state alive. Since MCP has no standard 'client cwd' field, the first step is always to create a session with an explicit working directory.

What is the difference between `outcome` and `terminal_state`?

`outcome` is the call result (success, deadline_exceeded, eof, error, invalid_session, terminated). `terminal_state` is a best-effort classification of the rendered terminal after the call (running, ready, password, confirm, repl, editor, pager, unknown). Terminal-state detection can be wrong, especially for custom prompts and cursor-heavy TUIs.

Is it safe to give an agent this kind of access?

PiloTY exposes unrestricted terminal access — treat it like giving the agent your keyboard. `send_password` suppresses logging/echo for that send but cannot prevent other programs from echoing secrets later. Session transcripts are written under `~/.piloty/`.

View repo Full PiloTY page