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