Enables programmatic control of a Node.js REPL session, allowing execution of JavaScript code and commands via sentinel-based completion detection.
Enables programmatic control of a Python REPL session, allowing execution of Python code and commands via sentinel-based completion detection.
Enables programmatic control of a Ruby (IRB) REPL session, allowing execution of Ruby code and commands via sentinel-based completion detection.
Enables programmatic control of a Zsh shell session, allowing execution of shell commands and scripts via sentinel-based completion detection.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pty-mcp start a bash session and run 'ls -la'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server exposing PTY (pseudo-terminal) sessions for AI agents. Enables programmatic control of shell sessions and REPLs through the Model Context Protocol.
Start and manage multiple PTY sessions
Run commands with sentinel-based completion detection
Works with any shell (bash, zsh, tcsh, fish, etc.)
Works with nested REPLs (Python, Node, Tcl, etc.)
Configurable session timeout and buffer size
Raw input support for interactive applications
Related MCP server: PTY MCP Server
uv add pty-mcpAdd to your MCP client configuration:
{
"mcpServers": {
"pty": {
"command": "uv",
"args": ["run", "pty-mcp"]
}
}
}Or run directly:
uv run pty-mcp --max-sessions 10 --log-dir /path/to/logsThe --log-dir option enables real-time session logging. When specified, each session's output is written immediately to a log file named pty_<command_name>_<session_id>.log (e.g., pty_bash_3a4b5c6d7e8f.log). The directory must exist; the server will error if it doesn't. You can watch logs in real-time with tail -f /path/to/logs/*.log.
start_sessionStart a new PTY session with any command or shell.
Parameters:
command (optional): Command/binary to execute (default: $SHELL or /bin/bash). Can be any executable like bash, python3, tcl, somebinary -a -b, etc. If args is not provided, the command string will be automatically parsed to extract arguments.
args (optional): List of arguments to pass to the command. If omitted, arguments will be parsed from the command string. Explicitly provide this when arguments contain spaces or special characters.
cwd (optional): Working directory
timeout_session (optional): Idle timeout (default: 86400)
buffer_size (optional): Scrollback buffer lines (default: 1000)
sentinel_command (optional): Command to echo sentinel (default: echo {sentinel})
Returns: Session ID
Examples:
# Start default shell (bash)
start_session()
# Start Python REPL
start_session(command="python3")
# Start custom binary with arguments (auto-parsed)
start_session(command="somebinary -a -b --args")
# Start with explicit args (for complex arguments)
start_session(command="somebinary", args=["-a", "-b", "--args"])
# Start Tcl shell in specific directory
start_session(command="tclsh", cwd="/path/to/project")run_commandRun a command and wait for completion.
Parameters:
session_id (required): Session ID from start_session
command (required): Command to run
timeout (optional): Timeout in seconds (default: 1800)
Returns: Command output
send_keysSend raw input without waiting for completion.
Parameters:
session_id (required): Session ID
keys (required): Raw input (use \n for Enter, \x03 for Ctrl+C)
get_bufferGet scrollback buffer contents.
Parameters:
session_id (required): Session ID
lines (optional): Number of lines from end
Returns: Buffer contents
stop_sessionStop and clean up a session.
Parameters:
session_id (required): Session ID to stop
set_sentinelChange the sentinel command for a session. Use when switching between shells/REPLs.
Parameters:
session_id (required): Session ID
sentinel_command (required): New sentinel command template with {sentinel} placeholder
list_sessionsList all active sessions with metadata.
When switching from a shell to a REPL (or between REPLs), use set_sentinel to update the sentinel command:
# Start with bash (default sentinel: echo {sentinel})
session_id = start_session()
# Run some bash commands
run_command(session_id, "ls -la")
# Switch to Python REPL
send_keys(session_id, "python3\n")
set_sentinel(session_id, "print('{sentinel}')")
# Now run Python commands
run_command(session_id, "print('hello from python')")
run_command(session_id, "2 + 2")
# Exit Python and switch back to bash
send_keys(session_id, "exit()\n")
set_sentinel(session_id, "echo {sentinel}")Common sentinel commands:
Bash/sh/zsh: echo {sentinel}
Python: print('{sentinel}')
Node.js: console.log('{sentinel}')
Tcl: puts {sentinel}
Ruby (irb): puts '{sentinel}'
# Install dependencies
uv sync
# Run tests
uv run pytest tests/ -vMIT
Get the scrollback buffer from a PTY session.
| Name | Required | Description | Default |
|---|---|---|---|
| lines | No | Number of lines to return from end of buffer. Omit for full buffer. | |
| session_id | Yes | The session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose whether the operation is read-only, destructive, or requires specific permissions. For a read operation, basic transparency is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure. It front-loads the purpose but does not detail parameters or behavior, making it minimally adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity and full schema coverage, the description is sufficient for basic use. However, it omits context like return format, behavior of the 'lines' parameter, and potential pitfalls (e.g., empty buffer).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The tool description adds no additional meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('scrollback buffer from a PTY session'). It is specific and distinguishes from siblings like run_command or list_sessions, though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as send_keys or start_session. The description does not mention prerequisites (e.g., session must be active) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all active PTY sessions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description is minimal. It does not disclose return format, side effects, or any behavioral traits beyond listing sessions. More detail could help the agent understand what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is efficiently front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and no annotations, the description is sufficient for a basic understanding. However, it lacks details on return format and any behavioral context, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the schema coverage is 100%. The description adds no parameter semantics, which is acceptable since no parameters exist. Score reflects baseline for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all active PTY sessions, using a specific verb and resource. It distinguishes from siblings which focus on buffers, commands, keys, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context but no guidance on when to use this tool versus alternatives or any exclusions. For a simple list tool, this is adequate but lacks explicit usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a command in a PTY session and wait for completion. Uses sentinel-based detection to know when command finishes.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The command to run | |
| timeout | No | Timeout in seconds to wait for command completion (default: 1800) | |
| session_id | Yes | The session ID returned by start_session |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partly covers behavior (waiting for completion, sentinel-based detection) but lacks details on side effects (e.g., consuming output), error handling, or timeout behavior. More transparency is needed for a safe PTY command tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) and front-loaded with key action and resource. However, it could be slightly more structured with a clear separation of purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description omits important context such as what the tool returns (e.g., command output, sentinel confirmation) or how to retrieve output. Given three parameters and complexity of PTY sessions, it is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are described in the input schema (100% coverage), so the description adds no extra semantic value beyond what is already provided in the schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Run a command in a PTY session and wait for completion', specifying the verb (run), resource (command in PTY session), and behavior. It distinguishes from sibling tools like send_keys, which sends keystrokes but doesn't wait for completion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'sentinel-based detection' but does not explicitly guide when to use this tool versus alternatives like send_keys or get_buffer. There is no 'when not to use' or differentiation from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send raw input to a PTY session without waiting for completion. Use for interactive input, Ctrl+C (send '\x03'), etc.
| Name | Required | Description | Default |
|---|---|---|---|
| keys | Yes | Raw input to send. Use \n for Enter, \x03 for Ctrl+C, etc. | |
| session_id | Yes | The session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. Reveals non-blocking behavior, but doesn't mention idempotency, authorization, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key info (send raw input, no wait), no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with 2 params and no output schema; description covers purpose, usage context, and parameter format adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both params, description adds value for 'keys' with concrete examples (\n, \x03). No extra detail for session_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Send raw input to a PTY session' (verb+resource) and distinguishes from siblings like run_command by noting it doesn't wait for completion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'without waiting for completion' and gives examples like Ctrl+C. Implies when to use vs run_command, but no explicit when-not or list of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the sentinel command for a session. Use when switching between shells/REPLs (e.g., from bash to python).
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID | |
| sentinel_command | Yes | New sentinel command template. Use {sentinel} placeholder. Examples: 'echo {sentinel}' (bash), "print('{sentinel}')" (python) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but does not disclose behavioral traits such as what a sentinel is, how it affects future commands, prerequisites (e.g., session must be active), or side effects. This leaves key behavior unexplained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with the action. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and full schema coverage, the description is adequate but missing some context about the sentinel concept and its role in session management, which would help an agent fully understand the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters (100% coverage) with descriptions. The description adds value by explaining how to use the sentinel_command parameter with the {sentinel} placeholder and providing examples, expanding on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states specific verb and resource ('Change the sentinel command for a session') and provides usage context with an example, effectively distinguishing it from sibling tools like run_command or send_keys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when switching between shells/REPLs') and gives a concrete example (bash to python), providing clear guidance without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new PTY session with any command or shell. Returns a session_id to use with other commands.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for the session | |
| args | No | Optional explicit arguments for the command. If omitted, arguments are parsed from the command string. Use this for arguments with spaces or special characters. | |
| command | No | Command/binary to execute (default: $SHELL or /bin/bash). Can be 'python3', 'somebinary -a -b', etc. Arguments are auto-parsed from the command string if 'args' is not provided. | |
| buffer_size | No | Scrollback buffer size in lines (default: 1000) | |
| timeout_session | No | Idle timeout in seconds (default: 86400) | |
| sentinel_command | No | Command template to echo sentinel. Use {sentinel} placeholder. Default: 'echo {sentinel}'. For Python REPL: "print('{sentinel}')" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full burden. It mentions starting a PTY session and returning an ID, but does not disclose resource allocation, idle timeout behavior (though parameters hint at it), or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the purpose, and contains no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, no output schema, no annotations), the description provides enough high-level context about starting a session and linking to other tools. The schema covers parameter details adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no additional meaning beyond the schema. It does not elaborate on parameters like cwd, args, or sentinel_command.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Start', resource 'PTY session', and the return value 'session_id'. It distinguishes well from sibling tools like list_sessions and stop_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is the first step to get a session_id for other commands, but it does not explicitly exclude alternatives or mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop and clean up a PTY session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID to stop |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states 'stop and clean up' without details on side effects, resource release, or whether it is destructive. With no annotations, the description fails to disclose behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is too minimal. It lacks context about when to stop, prerequisites, expected effects, and how it relates to sibling tools. An agent would need more information to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for session_id. The tool description adds no extra meaning; it neither clarifies format nor provides usage context beyond the schema. Baseline score for high coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Stop and clean up a PTY session.' clearly states the specific verb-action (stop and clean up) and the resource (PTY session). It distinguishes from siblings like start_session or list_sessions by indicating termination and cleanup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like send_keys or run_command. It lacks context such as prerequisites or indications for stopping a session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_bufferlist_sessionsrun_commandsend_keysset_sentinelstart_sessionstop_sessionEach tool has a clear, distinct purpose: session lifecycle (start, stop, list), command execution, interactive input, output retrieval, and sentinel configuration. No overlaps.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., start_session, get_buffer), making predictions easy.
7 tools is well-scoped for managing PTY sessions, covering creation, interaction, output, and cleanup without excess.
Core lifecycle and interaction are covered, but lacks tools for session details (e.g., size) or resizing, which are minor gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Build Apps and run code in 30 languages — sandboxed, with persistent sessions for agent loops.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/brkhrdt/pty-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
