@dwmkerr/shellwright-mcp-server

🖥️ shellwright

Playwright for the shell. AI-driven terminal automation, screenshots and video recording.

Finally. Your AI agents can close Vim

User: Open Vim. Tell me how to close it. Close it. Record this as a video.

Quickstart | Examples | MCP Tools | Configuration

Quickstart

Configure your LLM, IDE or whatever to use the Shellwright MCP server:

{
  "mcpServers": {
    "shellwright": {
      "command": "npx",
      "args": ["-y", "shellwright-mcp-server"]
    }
  }
}

Running Locally

Run the MCP server:

npm install
npm run dev

The server runs at http://localhost:7498/mcp.

Testing with the MCP Inspector

Open the MCP Inspector in another terminal and connect to http://localhost:7498/mcp to list and test tools:

# Open MCP inspector in another terminal.
npx @modelcontextprotocol/inspector

# Now connect to:
# http://localhost:7498/mcp

Testing with an Agent

Run the demo.py program to chat to an agent that has the Shellwright tool:

# Optionally setup your .env to specify configuration.
# cp ./demo/.env.sample .env && vi .env

# Install requirements and run the agent.
pip install -r ./demo/requirements.txt
python ./demo/demo.py

# Output:
# User (enter message): Show me what the htop tool looks like showing me my resources.

# ...or provide a message directly.
python ./demo/demo.py -- "Run a shell command to show me the names \
of the folders in this directory and take a screenshot and give me its path"

You will see logs from the MCP server and the demo agent:

Screenshots and videos by default will be written to ./output.

Examples

Have fun with some prompts:

Open Vim. Write a message saying how to close Vim. Close Vim. Give me a screenshot of each step and a GIF recording.

MCP Tools

Tool	Description
shell_start	Start a new PTY session
shell_send	Send input to a session
shell_read	Read the terminal buffer
shell_snapshot	Get terminal screen as text grid
shell_screenshot	Save terminal state to txt, svg, png
shell_record_start	Start recording for GIF export
shell_record_stop	Stop recording and export GIF
shell_stop	Stop a PTY session

Configuration

Variable	Parameter	Default	Description
PORT	--port, -p	7498	Server port ("SWRT" on a phone keypad)
THEME	--theme, -t	one-dark	Color theme (one-dark, one-light, dracula, solarized-dark, nord)
TEMP_DIR	--temp-dir	/tmp/shellwright	Directory for recording frames

TODO

• Video export (MP4/MOV) via ffmpeg
• Set screen size tool
• Better logging

License

MIT