{"id":"2f8310ed-c372-414d-8278-6ec4d91b5ccb","slug":"mcp-terminal-bridge","kind":"mcp","name":"MCP-Terminal-Bridge","summary":"Headless yet Powerful MCP server for terminal control: Launch, interact with, and monitor terminal applications through the Model Context Protocol. Written in Go","owner":"devdotbo","repoUrl":"https://github.com/devdotbo/MCP-Terminal-Bridge","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-06-12T11:18:57.000Z","addedAt":"2026-10-21T19:01:58.734Z","logoUrl":"https://avatars.githubusercontent.com/u/129651996?u=f1d14b54ddfa2eff9dc823e6f8dc2d47b4e7fa4c&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["browser-web","cloud-infra","memory-knowledge"],"tags":[],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-24T05:24:11.863Z","sample":false,"url":"https://conduits.dev/tools/mcp-terminal-bridge","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# TerminalBridge\n*Headless yet Powerful*\n\nAn MCP (Model Context Protocol) server that enables AI assistants to seamlessly control and interact with terminal/TUI applications.\n\n## Overview\n\nThis server acts as a bridge between AI assistants (like Claude) and terminal applications, providing:\n- Terminal application launching with PTY emulation\n- Visual output capture with ANSI support\n- Keyboard input simulation\n- Terminal state information\n\n## Current Implementation Status\n\n### Phase 1: Foundation (COMPLETE ✅)\n- ✅ All 9 MCP tools implemented and working\n- ✅ Session management with automatic cleanup\n- ✅ PTY wrapper for terminal control\n- ✅ Screen buffer with basic ANSI support\n- ✅ Special key mapping (arrows, function keys, Ctrl sequences)\n- ✅ Multiple output formats (plain, raw, ansi)\n- ✅ Concurrent session support\n- ✅ Build system with Makefile\n\n### Phase 2: Core Features (COMPLETE ✅)\n- ✅ Enhanced ANSI parser (supports CSI, SGR, OSC, DCS, and more)\n- ✅ Terminal resize support with SIGWINCH handling  \n- ✅ Structured logging throughout\n- ✅ Scrollback buffer support (1000 lines)\n- ✅ All unit tests passing\n- ✅ Proper renderRaw() with ANSI sequences\n- ✅ Multiple output formats including scrollback\n\n### Phase 3: Testing & Robustness (IN PROGRESS 🚧)\n- ✅ Comprehensive integration test framework\n- ✅ Tests for all 9 MCP tools\n- ✅ Test applications (echo, menu, progress)\n- ✅ 13 out of 18 integration tests passing\n- 🚧 Error recovery and session management\n- 🚧 Performance optimizations\n\n## Quick Start\n\n```bash\n# Install dependencies\ngo mod download\n\n# Build the server\nmake build\n\n# Build test applications\nmake test-apps\n\n# Run the server (stdio mode)\n./bin/terminalbridge\n\n# Or run directly\ngo run cmd/server/main.go\n\n# Run tests\nmake test\n\n# Test with example app (in another terminal)\ncd test/apps\n./echo\n```\n\n## MCP Tools\n\n### launch_app\nLaunch a new terminal application.\n```json\n{\n  \"command\": \"vim\",\n  \"args\": [\"test.txt\"],\n  \"env\": {\"TERM\": \"xterm-256color\"}\n}\n```\n\n### view_screen\nGet the current terminal content.\n```json\n{\n  \"session_id\": \"session-123\",\n  \"format\": \"plain\"  // or \"raw\", \"ansi\", \"scrollback\"\n}\n```\n\nOutput formats:\n- `plain`: Text only, no ANSI escape sequences\n- `raw`: Full terminal output with ANSI escape sequences\n- `ansi`: Debug format showing cursor position with ▮\n- `scrollback`: Includes scrollback buffer history\n\n### send_keys\nSend keyboard input to the terminal.\n```json\n{\n  \"session_id\": \"session-123\",\n  \"keys\": \"Hello World\"  // or \"Enter\", \"Ctrl+C\", etc.\n}\n```\n\n### Other Tools\n- `get_cursor_position`: Get current cursor position\n- `get_screen_size`: Get terminal dimensions\n- `resize_terminal`: Resize the terminal window\n- `restart_app`: Restart a session\n- `stop_app`: Terminate a session\n- `list_sessions`: List all active sessions\n\n## Configuration\n\nEnvironment variables:\n- `MCP_PORT`: Not used in current stdio implementation\n- `MAX_SESSIONS`: Maximum concurrent sessions (default: 100)\n- `SESSION_TIMEOUT`: Idle timeout in minutes (default: 30)\n- `LOG_LEVEL`: Logging level (default: info)\n\n## Implementation Notes\n\n- Uses `mark3labs/mcp-go` v0.31.0 for MCP protocol\n- Uses `creack/pty` v1.1.24 for terminal emulation\n- Runs in stdio mode (standard input/output)\n- Session cleanup runs every 5 minutes\n- Default terminal size: 80x24 (resizable via `resize_terminal` tool)\n- Structured JSON logging to stderr (configurable via LOG_LEVEL)\n- Enhanced ANSI parser supports most common escape sequences\n\n## Development\n\nSee `project.md` for complete technical design and `progress.md` for current development status.\n\n## Testing\n\n```bash\n# Run all tests\nmake test\n\n# Run with coverage\nmake test-coverage\n\n# Run integration tests\nmake test-integration\n\n# Run specific test suites\nmake test-terminal    # Terminal package tests\nmake test-session     # Session manager tests\n```\n\n## License\n\nMIT"}