Reported issues for Terminal MCP Server

Pod holds 21 of 131 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to Terminal MCP Server.

Most discussed

[Bug] Error: MCP error -32603: Failed to wait for condition: PTY error: Tmux session 'terminal-mcp-d83406bb-ac21-4af5-b0a0-1f9209716f41' no longer exists

Describe the bug

Error: MCP error -32603: Failed to wait for condition: PTY error: Tmux session 'terminal-mcp-d83406bb-ac21-4af5-b0a0-1f9209716f41' no longer exists

how to fix it? i see it too ofter

Steps to reproduce

claude add mcp terminal-mcp -- npx -y terminal-server-mcp

claude -p "use terminal-mcp to figure out with bug ... , run it in the loop until bug will not fix

Expected behavior

i expected no errors here

Actual behavior

`Error: MCP error -32603: Failed

Read the thread · 2025-12-26 · closed · external user · 2 comments

[Bug] libc 2.39 not found after `npx -y` on ubuntu 22.04

Describe the bug

npx -y mcp-server-terminal@latest

/home/slach/.cache/mcp-server-terminal/terminal-mcp: /lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.39' not found (required by /home/slach/.cache/mcp-server-terminal/terminal-mcp)

looks like latest package just doesn't work cause you require newer libc from your rust binary

ubuntu 22.04 have only libc 2.35

could we make fully static binary in rust without libc denedency?

Steps to reproduce

`npx -y mcp-server-terminal@lates

Read the thread · 2025-12-26 · closed · external user · 2 comments

[Bug][Emulator][General][P0] - Alt-screen buffer updates not captured in visual mode

Summary

In visual mode (tmux), terminal snapshots capture the initial render of applications using alternate screen buffers (via CSI ?1049h), but fail to reflect any dynamic updates after user interactions.

Steps to Reproduce

Create visual terminal session with TUI application that uses alt-screen:

{
  "command": "vim",
  "visual": true,
  "dimensions": {"rows": 30, "cols": 100}
}

Take initial snapshot:

terminal_snapshot({"session_id": "..."})

**Re

Read the thread · 2025-12-07 · closed · 2 comments

[Enabler][Schema][Gemini][P1] - Add JSON Schema transformation layer for AI client compatibility

Summary

Technical foundation work to transform schemars-generated JSON Schema (draft-2020-12) into formats compatible with various AI clients, starting with Gemini CLI.

Motivation

The schemars crate generates JSON Schema using draft-2020-12 features that some AI clients don't support:

$defs instead of definitions
anyOf with nullable: true patterns
Complex nested references

Gemini CLI fails with errors like:

Error: Invalid JSON schema for tool terminal_session_create

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/129) · 2025-12-06 · closed · 2 comments

### [Test] Input Tools - terminal_type and terminal_press_key Navigation

## Epic
Epic: Comprehensive MCP Tools Testing with ffice TUI

## Description
Test `terminal_type` and `terminal_press_key` tools for reliable keyboard interaction with ffice TUI application including text entry, navigation, function keys, and control sequences.

**Test Application**: `/mnt/d/Projects/ffice-suite/epic-ff-ice-r1-flight-filing-service/ffice-bridge/ffice-tui/bin/ffice`

## Acceptance Criteria
- [ ] Text entry: Characters appear correctly in input fields
- [ ] Special characters: Spa

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/114) · 2025-12-03 · closed · 2 comments

### [Test] terminal_snapshot - Element Detection with ffice TUI

## Epic
Epic: Comprehensive MCP Tools Testing with ffice TUI

## Description
Validate `terminal_snapshot` tool's element detection engine using ffice TUI's rich interface (borders, menus, tables, buttons, input fields, selection states).

**Test Application**: `/mnt/d/Projects/ffice-suite/epic-ff-ice-r1-flight-filing-service/ffice-bridge/ffice-tui/bin/ffice`

## Acceptance Criteria
- [ ] Border detection: Window borders detected with priority 100
- [ ] Menu detection: Menu items detected with re

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/113) · 2025-12-03 · closed · 2 comments

### [Test] terminal_session_create - Headless and Visual Mode Validation

## Epic
Epic: Comprehensive MCP Tools Testing with ffice TUI

## Description
Test `terminal_session_create` MCP tool with ffice TUI application in both headless (PTY-only) and visual (terminal window) modes to validate session initialization, configuration, and lifecycle management.

**Test Application**: `/mnt/d/Projects/ffice-suite/epic-ff-ice-r1-flight-filing-service/ffice-bridge/ffice-tui/bin/ffice`

## Acceptance Criteria
- [ ] Headless mode: Sessions create successfully with default dimens

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/112) · 2025-12-03 · closed · 2 comments

### [Critical Bug] terminal_snapshot hangs indefinitely due to blocking PTY reads

## Problem

`terminal_snapshot` hangs indefinitely when called with `idle_threshold_ms` parameters (500ms, 1000ms, etc.), never returning and blocking all snapshot operations.

**Symptoms**:
- Tool invocation logs: `Capturing terminal snapshot: session_id=..., idle_threshold_ms=Some(500)`
- Function never completes
- No timeout is respected
- Process must be killed manually

**Affected Operations**:
- ✅ `terminal_snapshot` - PRIMARY
- ⚠️ `terminal_wait_for` - Uses similar waiting logic
- ⚠️ Any 

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/99) · 2025-12-03 · closed · 2 comments

## Most recent

### [Task][Documentation][Windows][P3] - Windows testing and documentation

## Summary

Test terminal-mcp on Windows and update documentation with Windows-specific instructions.

## Parent Epic

#147 - Full Windows Support

## Testing Plan

### Manual Testing Checklist

- [ ] Install via npm on Windows
- [ ] Run `terminal-mcp --headless` 
- [ ] Test with Claude Desktop on Windows
- [ ] Test with Gemini CLI on Windows
- [ ] Test TUI apps: htop equivalent, vim, etc.
- [ ] Test Go TUI apps (Bubble Tea)
- [ ] Test Python TUI apps (Textual, Rich)

### Test Scenarios

1. **He

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/151) · 2025-12-18 · open · 1 comment

### [Task][Platform][Windows][P1] - Basic Windows compilation fix

## Summary

Add platform guards to enable Windows compilation. Currently blocked by Unix-specific `libc::kill` call.

## Parent Epic

#147 - Full Windows Support

## Problem

```rust
// session.rs:480 - Unix only!
unsafe {
    libc::kill(handle.pid as i32, libc::SIGTERM);
}

Solution

1. Platform-specific process termination

#[cfg(unix)]
fn kill_process(pid: u32) {
    unsafe { libc::kill(pid as i32, libc::SIGTERM); }
}

#[cfg(windows)]
fn kill_process(pid: u32) {
    use std

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/148) · 2025-12-18 · closed · 1 comment

### [Epic][Platform][Windows][P2] - Full Windows Support

## Summary

Epic tracking issue for full Windows platform support. This enables Windows developers to use terminal-mcp for TUI/CLI application debugging and automation.

## Motivation

- Windows is a major development platform
- Many TUI applications (Go, Rust, Python) run on Windows
- Current codebase uses Unix-specific APIs (`libc::kill`, `tmux`)

## Current State

| Component | Status |
|-----------|--------|
| PTY handling (`portable-pty`) | ✅ Cross-platform |
| Visual terminal implementatio

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/147) · 2025-12-18 · open · 1 comment

### [Feature] windows support

### Problem description

Thanks for really great project. Could you add support Windows for your project?

### Proposed solution

Hope current rust implementation allow to add support windows

### Alternatives considered

_No response_

### Use case

I developed some TUI applications in golang and would like to debug them with code agents under Windows.

### Would you be willing to contribute?

None

### Additional context

_No response_

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/146) · 2025-12-14 · open · external user · 1 comment

### [Bug][Schema][Gemini][P1] - Missing $schema field transformation causes Gemini rejection

## Summary
Gemini CLI rejects terminal-mcp tool schemas with error: `no schema with key or ref "https://json-schema.org/draft/2020-12/schema"`. The schema transformation layer transforms `$defs` and `anyOf` patterns but does NOT update the `$schema` field itself from draft-2020-12 to draft-07.

## Steps to Reproduce
1. Install terminal-mcp v1.0.3 via npm
2. Configure Gemini CLI to use terminal-mcp
3. Try to invoke `terminal_session_create` tool
4. Observe schema validation errors

## Expected Be

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/145) · 2025-12-10 · closed · 1 comment

### [Bug][Session][General][P1] - Visual mode session creation fails after first session closed

## Summary
Creating terminal sessions with `visual: true` fails intermittently after the first session is closed, making iterative testing workflows impossible.

## Steps to Reproduce

**Attempt 1** - Initial Session (SUCCESS):
```json
terminal_session_create({
  "command": "bash",
  "visual": true,
  "dimensions": {"rows": 30, "cols": 100}
})

// Response:
{
  "session_id": "8ef1cadb-4b85-40f2-af78-74901841800a",
  "message": "Session created successfully"
}

✅ Session works correctly

**Clo

Read the thread · 2025-12-07 · closed · 1 comment

[Bug][Detector][General][P3] - Snapshot elements detection produces false positives

Summary

The snapshot elements array incorrectly identifies UI elements. Git branch indicators are detected as "buttons", and random text is detected as "progress bars".

Steps to Reproduce

Open a terminal with a git repository prompt showing branch name (e.g., user@host:/path(main)$)
Take a snapshot with terminal_snapshot
Examine the elements array in the response

Expected Behavior

Elements should accurately represent interactive UI components:

Buttons should be clic

Read the thread · 2025-12-07 · closed · 1 comment

[Bug][Emulator][General][P2] - TUI/Interactive menu rendering issues in raw_text

Summary

Interactive TUI menus (arrow key navigation, selection prompts) are only partially visible in raw_text. The rendered snapshot doesn't properly capture the menu state with correct line breaks and structure.

Steps to Reproduce

Create a terminal session
Run a command that shows an interactive menu (e.g., fzf, selection prompt, breakdown wizard)
Take a snapshot with terminal_snapshot
Examine the raw_text field

Expected Behavior

Menu should be clearly visible wi

Read the thread · 2025-12-07 · closed · 1 comment

[Bug][Emulator][General][P2] - clear command doesn't reset terminal buffer

Summary

The clear command doesn't properly clear the terminal buffer. Old content persists and mixes with new content in snapshots.

Steps to Reproduce

Create a terminal session
Run several commands that produce output
Run clear command
Run new commands
Take a snapshot with terminal_snapshot

Expected Behavior

Buffer should be cleared after clear command. Snapshot should show only content after the clear.

Actual Behavior

Old content remains in raw_text:


[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/139) · 2025-12-07 · closed · 1 comment

### [Bug][Session][General][P2] - cwd parameter not honored in terminal_session_create

## Summary
The `cwd` parameter in `terminal_session_create` is ignored. Sessions always start in the default directory regardless of the specified working directory.

## Steps to Reproduce
1. Call `terminal_session_create` with:
   ```json
   {
     "command": "bash",
     "cwd": "/mnt/d/Projects/upm-framework/tmp/litpay"
   }

Observe the terminal prompt after session creation
Run pwd to verify current directory

Expected Behavior

Terminal should start in `/mnt/d/Projects/upm-f

Read the thread · 2025-12-07 · closed · 1 comment

[Bug][Emulator][General][P1] - Screen buffer corruption after ASCII art display

Summary

After displaying ASCII art banners (e.g., installation wizards with box-drawing characters), the terminal screen buffer becomes permanently corrupted. Subsequent commands and their output are garbled or mixed with old content.

Steps to Reproduce

Create a visual terminal session
Run a command that displays ASCII art with Unicode box-drawing characters (╔═╗║╚╝)
Run subsequent commands
Take snapshots or read output

Expected Behavior

Screen should render correctly afte

Read the thread · 2025-12-07 · closed · 1 comment

[Bug][Session][General][P1] - idle wait returns immediately (0ms) without waiting

Summary

The terminal_wait_for with idle: true returns immediately with waited_ms: 0 even when commands are still executing or output hasn't appeared yet.

Steps to Reproduce

Create a terminal session
Run a command that takes time (e.g., AI-powered breakdown, npm install)

Immediately call:

{
  "session_id": "...",
  "idle": true,
  "timeout_ms": 30000
}

Expected Behavior

Should wait until terminal is truly idle:

Command has completed exe

Read the thread · 2025-12-07 · closed · 1 comment

[Bug][Snapshot][General][P0] - Command output not captured in snapshots

Summary

Commands are typed and executed, but their output never appears in terminal_snapshot or terminal_read_output. Only the command itself is visible in raw_text.

Steps to Reproduce

Create a terminal session with terminal_session_create
Type and execute a command: ./.upm/bin/upm create epic "Test"
Wait for execution using terminal_wait_for
Call terminal_snapshot or terminal_read_output

Expected Behavior

Output should show the command result (success mess

Read the thread · 2025-12-07 · closed · 1 comment

The remaining reports are on the project's issue tracker.

Reported issues for Terminal MCP Server

Most discussed

[Bug] Error: MCP error -32603: Failed to wait for condition: PTY error: Tmux session 'terminal-mcp-d83406bb-ac21-4af5-b0a0-1f9209716f41' no longer exists

Describe the bug

Steps to reproduce

Expected behavior

Actual behavior

[Bug] libc 2.39 not found after npx -y on ubuntu 22.04

Describe the bug

Steps to reproduce

[Bug][Emulator][General][P0] - Alt-screen buffer updates not captured in visual mode

Summary

Steps to Reproduce

[Enabler][Schema][Gemini][P1] - Add JSON Schema transformation layer for AI client compatibility

Summary

Motivation

Solution

1. Platform-specific process termination

[Bug][Detector][General][P3] - Snapshot elements detection produces false positives

Summary

Steps to Reproduce

Expected Behavior

[Bug][Emulator][General][P2] - TUI/Interactive menu rendering issues in raw_text

Summary

Steps to Reproduce

Expected Behavior

[Bug][Emulator][General][P2] - clear command doesn't reset terminal buffer

Summary

Steps to Reproduce

Expected Behavior

Actual Behavior

Expected Behavior

[Bug][Emulator][General][P1] - Screen buffer corruption after ASCII art display

Summary

Steps to Reproduce

Expected Behavior

[Bug][Session][General][P1] - idle wait returns immediately (0ms) without waiting

Summary

Steps to Reproduce

Expected Behavior

[Bug][Snapshot][General][P0] - Command output not captured in snapshots

Summary

Steps to Reproduce

Expected Behavior

[Bug] libc 2.39 not found after `npx -y` on ubuntu 22.04