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 | Installation | Configuration | MCP Tools | Developer Guide

快速入门

配置您的LLM， 克劳德代码, 光标 或者使用Shellwright MCP服务器：

{
  "mcpServers": {
    "shellwright": {
      "command": "npx",
      "args": ["-y", "@dwmkerr/shellwright"]
    }
  }
}

使用如下提示：

使用shellwright打开Vim。写一条消息，说明如何关闭Vim。关闭Vim。给我每个步骤的屏幕截图和GIF记录，将屏幕截图和视频保存到。/输出”。

将保存视频记录以及多种格式的屏幕截图。

检查 例子 或 安装 更多详细信息，请参阅指南。我还用它为我的书制作了丰富的录音 有效外壳.

本地运行

以HTTP模式运行MCP服务器进行本地开发：

npm install
npm run dev:http

# Or add parameters if needed...
npm run dev:http -- --font-size 32

服务器运行在 http://localhost:7498/mcp.

与MCP检查员一起进行测试

打开 MCP检查员 在另一个终端中并连接到 http://localhost:7498/mcp 列出和测试工具：

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

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

使用代理进行测试

跑吧 demo.py 与具有Shellwright工具的代理聊天的程序。请注意，您必须使Shellwright MCP服务器在HTTP模式下运行（例如。 npm run dev:http):

# 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"

您将看到来自MCP服务器和演示代理的日志：

Screenshot of the MCP server and demo agent

默认情况下，截图和视频将写入 ./output.

例子

享受一些提示。

做一些Vim的事情：

打开Vim。写一条消息，说明如何关闭Vim。关闭Vim。给我一张每一步的截图和一张GIF录像。

Screenshot: Examples - Vim

打开K9S。检查“代理”类型的资源。给我一个GIF录音，并沿途截图。

Screenshot: Examples - K9S Agents

截取带边框的屏幕截图：

打开克劳德代码。使用名为“Shellwright”的macOS窗口边框进行截图。

Screenshot: Examples - Bordered Screenshot

使用 htop:

打开htop并显示资源最密集的流程。

Screenshot: Examples - HTOP

打开vim，创建validate.py，检查参数是否为英国邮政编码。打印✓ or ✗ 对于每一个。然后在一组英国邮政编码（有效和无效）上运行：python3-validate.py，如“SW1A 1AA”“invalid”“M1 1AA”。录制为视频。沿途拍摄2-3张截图。

Screenshot: Example - UK Postcode Validation

安装

克劳德代码

# Install for current project. Use '--scope user' for for user-wide.
claude mcp add --scope project shellwright -- npx -y @dwmkerr/shellwright

# Configure via command line parameters (or env vars) if needed.
claude mcp add --scope project shellwright -- npx -y @dwmkerr/shellwright \
  --log-path /tmp/shellwright/log.jsonl

# Uninstall. Same comment on 'scope'.
claude mcp remove --scope project shellwright

游标/VS代码/其他MCP客户端

添加到MCP配置文件中：

{
  "mcpServers": {
    "shellwright": {
      "command": "npx",
      "args": ["-y", "@dwmkerr/shellwright"]
    }
  }
}

配置

LLM也可以提供一些配置，只需提示即可：

• 终端尺寸：例如：“使用80x24的终端进行录制”
• 主题：例如：“为这段录音使用德古拉主题”

MCP工具

外壳启动

使用命令启动新的PTY会话。列、行和主题是可选的，默认值可以在 配置:

启动正在运行的shell会话 bash:

{
  "command": "bash",
  "cols": 80,
  "rows": 24
}

使用登录模式shell和特定主题启动会话：

{
  "command": "bash",
  "args": ["--login", "-i"],
  "theme": "dracula"
}

可用主题（请参见 主题指南 用于预览）：

Themes

响应包含shell会话ID（因为可以运行多个shell会话）和主题：

{
  "shell_session_id": "shell-session-a1b2c3",
  "theme": "dracula"
}

shell_send

向PTY会话发送输入。在发送输入前后返回完整的终端缓冲区（纯文本，无ANSI代码），以便LLM可以准确地看到屏幕上发生了什么变化：

{
  "session_id": "shell-session-a1b2c3",
  "input": "ls -la\n",
  "delay_ms": 100
}

这 delay_ms 参数控制在发送输入后等待多长时间才能捕获 bufferAfter （默认值：100ms）。慢速命令增加。

响应包括发送输入之前和之后的终端缓冲区：

{
  "success": true,
  "bufferBefore": "$ _",
  "bufferAfter": "$ ls -la\ntotal 24\ndrwxr-xr-x  5 user staff ...\n$ _"
}

shell_read

读取当前终端缓冲区。使用 raw: true 包括ANSI转义码：

{
  "session_id": "shell-session-a1b2c3",
  "raw": false
}

响应是纯文本形式的终端内容（截断为8KB以避免上下文溢出）：

total 24
drwxr-xr-x  5 user staff  160 Dec 18 10:00 .
drwxr-xr-x 10 user staff  320 Dec 18 09:00 ..
-rw-r--r--  1 user staff 1234 Dec 18 10:00 README.md

外壳_滤网

将终端捕获为PNG和SVG格式。还保存ANSI和纯文本版本。通过 name 无延期(.png 自动添加）。可选择添加macOS风格的窗口边框（默认情况下为关闭）：

{
  "session_id": "shell-session-a1b2c3",
  "name": "my-screenshot",
  "border": { "style": "macos", "title": "Terminal" }
}

响应包含 download_png_url 和 download_svg_url 让curl在本地保存文件：

{
  "filename": "my-screenshot.png",
  "download_png_url": "http://localhost:7498/files/mcp-.../screenshots/my-screenshot.png",
  "download_svg_url": "http://localhost:7498/files/mcp-.../screenshots/my-screenshot.svg",
  "hint": "Use curl -o   to save the file"
}

shell_record_start

开始录制GIF导出的帧。以指定的FPS捕获帧（默认值为10，最大值为30，通过重复相同帧进行压缩）。可选 border 参数（与 shell_screenshot)将窗口镀铬应用于每一帧：

{
  "session_id": "shell-session-a1b2c3",
  "fps": 10,
  "border": { "style": "macos", "title": "Terminal" }
}

响应确认录制已开始：

{
  "recording": true,
  "fps": 10,
  "frames_dir": "/tmp/shellwright/.../frames"
}

外壳记录停止

停止录制并将帧渲染为GIF：

{
  "session_id": "shell-session-a1b2c3",
  "name": "my-recording"
}

响应包含 download_gif_url 让curl在本地保存文件：

{
  "filename": "my-recording.gif",
  "download_gif_url": "http://localhost:7498/files/mcp-.../recordings/my-recording.gif",
  "hint": "Use curl -o   to save the file",
  "frame_count": 42,
  "duration_ms": 4200
}

外壳停止

停止PTY会话并清理资源：

{
  "session_id": "shell-session-a1b2c3"
}

响应确认会话已停止：

{
  "success": true
}

MCP提示 也可用于常见的工作流，如vim编辑和录制会话。看 src/prompts.ts.

故障排除

默认情况下，MCP服务器会将屏幕截图、视频帧和GIF（如果需要）写入临时位置。此位置包括MCP会话ID和Shell会话ID（一个MCP会话可以有多个Shell会话）：

# Show the contents of an MCP and shell session.
tree /tmp/shellwright/mcp-session-16281bdf-7881-458a-8bee-475b02d000d2/shell-session-c66b8a

# Output:
# .
# ├── frames                         # Frames for the GIF recording. These are 
# │   └── frame000000.png            # cleaned up at the end of the session.
# ├── recordings
# │   └── vim_tutorial_complete.gif  # The GIF recording (if requested).
# └── screenshots
# ├── step1_initial_terminal.ansi    # Individual screenshot w/ ansi color etc.
# ├── step1_initial_terminal.png     # Screenshot as PNG (ANSI->SVG->PNG).
# └── step1_initial_terminal.svg     # The SVG intermediate.
# └── step1_initial_terminal.txt     # Screenshot as plain text.

您可以检查原始 txt 用于对屏幕截图内容进行故障排除的文件。你可以看到 ansi 包含格式和颜色代码的内容。最后，您可以打开 png 文件-这些是通过转换 ansi 转换为SVG（使用代码中定义的主题），然后将SVG转换为PNG。检查缓冲区的纯文本内容，或原始ansi，或格式如下：

# Show plain text. Make sure you are in the shell session temp directory.
cat ./k9s_initial_view.txt

# Show formatted ANSI. Good for troubleshooting color codes.
cat ./k9s_initial_view.ansi

开发者指南

要使用Cursor、VS Code或其他MCP客户端测试本地更改，请首先构建项目，然后将其配置为使用您的本地构建：

npm run build

{
  "mcpServers": {
    "shellwright-dev": {
      "command": "node",
      "args": ["/path/to/shellwright/dist/index.js"]
    }
  }
}

跑 npm run build 更改后，重新启动MCP客户端。

对于使用热重载的HTTP模式开发：

npm run dev:http

克劳德代码

要使用Claude Code测试本地开发更改，请将本地构建添加为MCP服务器：

# From the shellwright repo root - build first!
npm run build
claude mcp add shellwright-dev --scope project -- node "${PWD}/dist/index.js"

这将注册您的本地版本，以便您可以在发布之前测试更改。

贡献者

感谢所有贡献者！

fahd04 💻

该项目遵循 所有贡献者 规范。欢迎任何形式的贡献！

许可证

麻省理工学院