How to add PiloTY to Cursor

Persistent, interactive PTY terminal for AI agents over MCP — SSH, REPLs, password prompts, long-running jobs. Paste the config into ~/.cursor/mcp.json and restart Cursor.

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

Cursor 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

1Open Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
2Paste the PiloTY config below into the "mcpServers" object.
3Fill in placeholder secrets, then save.
4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
5Ask Cursor to use one of PiloTY's tools to confirm it's connected.

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 Cursor

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 + Cursor FAQ

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the PiloTY config there under the "mcpServers" key and restart the client.

Is PiloTY safe to use with Cursor?

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