REPL MCP Server

A universal REPL session manager supporting Python, Node.js, Ruby, and more, with session management and LLM-assisted recovery.

A simple MCP server for managing REPL sessions. Provides basic tools to create and execute commands in various REPLs and shells, with an integrated Web UI for browser-based session monitoring.

Working with remote REPLs (like Rails console on production servers) often forces you to cram complex operations into single commands since losing connection means losing your session state. This tool enables persistent REPL sessions that survive individual command executions, allowing you to work naturally with interactive environments through AI agents. The integrated Web UI provides browser-based monitoring for session observation.

- Multiple REPL Support: Python, IPython, Node.js, Ruby (pry, irb), bash, zsh
- Session Management: Create, execute commands, and destroy REPL sessions
- Web UI Integration: Browser-based terminal monitoring for session observation
- Customizable Setup: Configure setup commands and environment variables
- Cross-Platform: Works on Windows, macOS, and Linux

- Timeout Recovery: LLM assistance when commands timeout
- Session Learning: Remembers prompt patterns within sessions

- Session URLs:http://localhost:8023/session/SESSION_ID- Monitor sessions in browser
- Dynamic Ports: Auto-selects available ports starting from 8023
- Cross-Platform: Works on any device with modern browser
- Real-time: Live terminal output via WebSocket connection

Click the button above or add to your.vscode/mcp.json:

{ "servers": { "repl-mcp": { "command": "npx", "args": ["-y", "repl-mcp@latest"] } } }

claude mcp add repl-mcp -- npx -y repl-mcp@latest

{ "mcpServers": { "repl-mcp": { "command": "npx", "args": ["-y", "repl-mcp@latest"] } } }

- Clone this repository
- Install dependencies:npm install
- Build the project:npm run build
- Add to your MCP settings:

{ "mcpServers": { "repl-mcp": { "command": "node", "args": ["path/to/repl-mcp/build/index.js"] } } }

Create a new REPL session with preset or custom configuration. Use displayName to set a custom name that appears in the browser tab title. Returns a webUrl that can be opened in a browser to monitor the session via Web UI.

- presetConfig(optional): Name of predefined configuration
- displayName(optional): Custom display name for the session (shown in browser tab)
- customConfig(optional): Custom configuration object

{ "presetConfig": "pry", "displayName": "My Ruby Session" }

{ "displayName": "Custom Python Session", "customConfig": { "type": "python", "shell": "bash", "commands": ["python3"], "timeout": 10000 } }

{ "success": true, "sessionId": "abc123", "config": "Ruby Pry REPL", "webUrl": "http://localhost:8023/session/abc123" }

- sessionId: Unique session identifier (6-character format)
- webUrl: Browser URL for session monitoring
- config: Configuration name used

- sessionId: The session ID
- input: Input text to send to the session
- options(optional): Input options object

- wait_for_prompt(default: false): Wait for prompt to return
- timeout(default: 30000): Timeout in milliseconds
- add_newline(default: true): Add newline to input

{ "sessionId": "abc123", "input": "puts 'Hello, World!'", "options": { "wait_for_prompt": true } }

List all active REPL sessions. Each session includes a webUrl for browser access.

- sessions: Array of session objects with webUrl for each
- Each session includes: id, name, type, status, webUrl, etc.

Get detailed information about a specific session. Includes webUrl for browser access.

- session: Detailed session information
- webUrl: Browser URL for session monitoring

List all available predefined REPL configurations.

Send a signal (like Ctrl+C, Ctrl+Z) to interrupt or control a REPL session process.

- sessionId: The session ID
- signal: Signal to send (SIGINT,SIGTSTP,SIGQUIT)

{ "sessionId": "abc123", "signal": "SIGINT" }

Note on Windows:On Windows, onlySIGINTis practically effective. It is sent as aCtrl+Cevent and can be used to interrupt running commands or terminate compatible processes like Node.js REPLs.SIGTSTPandSIGQUIThave no effect.

Mark a session as ready with a specific prompt pattern. Used during session recovery.

- sessionId: The session ID
- pattern: Prompt pattern (regex or literal string)

{ "sessionId": "abc123", "pattern": "❯ " }

Wait additional time for a session to become ready.

- sessionId: The session ID
- seconds: Number of seconds to wait

{ "sessionId": "abc123", "seconds": 5 }

- sessionId: The session ID
- reason: Reason for failure

{ "sessionId": "abc123", "reason": "Process crashed" }

Note: Each REPL tool must be installed and available in your PATH.

- pry: Ruby Pry REPL with advanced debugging features
- irb: Ruby IRB REPL with standard functionality
- ipython: Enhanced Python REPL with rich features
- node: Node.js JavaScript REPL
- python: Standard Python REPL

- bash: Bash shell environment
- zsh: Zsh shell environment (with Oh My Zsh support)

- rails_console: Rails console with bundle exec
- rails_console_production: Production Rails console

When sessions timeout or become unresponsive, you can use recovery tools:

- send_signal_to_session- Send Ctrl+C, Ctrl+Z, or other signals to interrupt processes
- set_session_ready- Mark session ready when you detect a working prompt
- wait_for_session- Wait longer for slow commands to complete
- mark_session_failed- Mark session as failed when recovery isn't possible

Prompt patterns learned during recovery are remembered for the session duration.

{ "tool": "create_session", "arguments": { "presetConfig": "python", "displayName": "My Python Session" } }

{ "success": true, "sessionId": "xyz789", "config": "Python REPL", "webUrl": "http://localhost:8023/session/xyz789" }

{ "tool": "send_input_to_session", "arguments": { "sessionId": "xyz789", "input": "print('Hello from REPL!')", "options": { "wait_for_prompt": true } } }

To monitor a session, create it using MCP tools and open thewebUrlfrom the response in a browser. This allows you to observe real-time terminal activity.
- Create sessionvia MCP to get awebUrl.
- Open URLin a browser (e.g.,http://localhost:8023/session/xyz789), manually or using automation tools like Playwright MCP.
- Observethe live terminal.

When a command times out or hangs, you can recover the session:

{ "tool": "send_signal_to_session", "arguments": { "sessionId": "xyz789", "signal": "SIGINT" } }

{ "tool": "set_session_ready", "arguments": { "sessionId": "xyz789", "pattern": "❯ " } }

- Unique session ID: 6-character format for easy identification and management
- Configuration details: REPL type, shell, setup commands, etc.
- Current status: initializing, ready, executing, error, terminated
- Command history: Record of executed commands
- Last output and errors: Most recent execution results
- Creation and activity timestamps: Session lifecycle tracking
- Learned prompt patterns: Custom patterns discovered through LLM assistance
- Web UI access: Browser URL for session monitoring
- Initialization: Session created with specified configuration
- Ready: Session prepared for command execution
- Executing: Command being processed
- Learning: LLM assistance for prompt detection (when needed)
- Optimized: Learned patterns enable fast execution

The server provides comprehensive error handling with intelligent recovery:

- Session creation failures: Clear error messages with diagnostic information
- Command execution timeouts: Graceful timeout handling with retry options
- REPL crashes and recovery: Automatic detection and session state management
- Invalid command detection: Input validation and error reporting

- Prompt detection failures: Automatic LLM consultation for unknown prompts
- Adaptive timeout handling: Smart waiting based on command complexity
- Custom environment support: Dynamic learning for non-standard shells
- Contextual error analysis: Rich error information for troubleshooting

{ "success": false, "error": "Session not found", "executionTime": 0 }

{ "success": false, "error": "Timeout - LLM guidance needed", "question": "Session timed out. What should I do?", "questionType": "timeout_analysis", "canContinue": true, "context": { "sessionId": "...", "rawOutput": "..." } }

This will start TypeScript in watch mode for development.

- Usescmdorpowershellas default shell
- Some REPL features may behave differently
- Signal Handling:OnlySIGINTis effectively supported. It is translated to aCtrl+Cevent, which can stop most command-line tools and exit REPLs like Node.js.SIGTSTP(Ctrl+Z) andSIGQUIT(Ctrl+\) are not supported by the Windows console and will have no effect.

- Usesbashorzshas default shell
- Full feature support
- Session creation fails: Check that the required REPL command is installed and accessible
- Commands timeout consistently: Increase timeout value or check REPL responsiveness
- REPL not found: Ensure the REPL executable is in your PATH
- Port conflicts: The server automatically finds available ports starting from 8023
- Browser terminal not responsive: Check that JavaScript is enabled and try refreshing
- Session URL not working: Verify the session is still active and the port is correct
- Terminal size issues: The terminal uses 132x43 size for better application compatibility
- Session hangs: Usesend_signal_to_sessionwithSIGINTto interrupt stuck processes
- Pattern not working: Useset_session_readywith the correct prompt pattern
- Commands timeout: Trywait_for_sessionfor slow commands orsend_signal_to_sessionto interrupt

- Custom prompts: Useset_session_readyto specify your prompt pattern
- Nested environments: Usewait_for_sessionfor environments that need time to settle
- Stuck processes: Usesend_signal_to_sessionto interrupt long-running commands

- Session learning: Patterns learned during LLM assistance improve subsequent commands
- Multiple sessions: Each session learns independently

- REPL_MCP_DEBUG=1: Enable verbose debug logging for performance troubleshooting and development

Enable detailed debugging by checking thedebugLogsfield in responses:

{ "success": true, "output": "...", "debugLogs": [ "2025-06-22T15:31:15.504Z: [DEBUG session_xxx] Prompt detected: true", "2025-06-22T15:31:15.505Z: [DEBUG session_xxx] Learned new prompt pattern: '∙'" ] }

Contributions are welcome! The LLM-assisted features make it easy to add support for new shell environments and REPL types. When contributing:
- Test with different shells: Ensure compatibility across bash, zsh, and other environments
- Consider prompt variations: Test with custom prompts and themes
- Update configurations: Add new predefined configs for common setups
- Document LLM patterns: Share successful prompt patterns for others

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Agent-native developer Q&A API with MCP + A2A endpoints for citations, job pickup, and answer submission.

MCP bridge that lets Claude Code delegate heavy tasks to the Antigravity CLI (agy) — purpose-built tools, model routing with fallback, session continuity, and output truncation to save Claude's context and tokens.

Embeds intelligent guidance into AI workflows to organize development and ensure quality.

Open-source AI coding stack — bundled MCP servers, agent runtime, and developer tooling for shipping AI-native dev tools.

Local agent workbench bundling OpenHands, Goose, Aider, and ashlrcode against one local LLM, with ashlr-plugin MCP servers pre-wired.

Async Parallel Antigravity for Codex & Claude Code