{"_id":"@andrewleech/viperide-mcp","name":"@andrewleech/viperide-mcp","dist-tags":{"next":"0.5.2-mcp.1","latest":"0.5.2-mcp.1"},"versions":{"0.5.2-mcp.1":{"name":"@andrewleech/viperide-mcp","version":"0.5.2-mcp.1","description":"MCP server for controlling ViperIDE, a MicroPython/CircuitPython IDE. Connects to devices via USB serial, manages files, executes code, and provides full REPL access.","type":"module","main":"server/index.js","bin":{"viperide-mcp":"server/index.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","open":"^10.1.0","serialport":"^12.0.0","ws":"^8.18.0","zod":"^3.24.0"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/andrewleech/ViperIDE.git","directory":"mcp"},"homepage":"https://viper-ide.org","keywords":["mcp","micropython","circuitpython","ide","viperide","serial","repl","embedded"],"_id":"@andrewleech/viperide-mcp@0.5.2-mcp.1","bugs":{"url":"https://github.com/andrewleech/ViperIDE/issues"},"_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-AyHgLbZywKMMWFFYV35s3w19XTmQcHSrHWRhdWl4EmqMrziFHJYxvoTo3z8AX570/MsnHBJsZd+TJPGzJ8eW4A==","shasum":"18f917f75377aad38b2dfe6f4d9b4a0497e99554","tarball":"https://registry.npmjs.org/@andrewleech/viperide-mcp/-/viperide-mcp-0.5.2-mcp.1.tgz","fileCount":27,"unpackedSize":12059089,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@andrewleech%2fviperide-mcp@0.5.2-mcp.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIG+LviBIYtBDBpXfARBxb3tMHUOycBvVUqCYKgpJviCUAiByM0yLcNlnRrqcd3LQQrfsZAtUpAirDBgP5AsOHfhLzw=="}]},"_npmUser":{"name":"andrewleech","email":"andrew@alelec.net"},"directories":{},"maintainers":[{"name":"andrewleech","email":"andrew@alelec.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/viperide-mcp_0.5.2-mcp.1_1776879263939_0.1736656300985966"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-22T17:34:23.835Z","0.5.2-mcp.1":"2026-04-22T17:34:24.212Z","modified":"2026-04-22T17:34:24.687Z"},"maintainers":[{"name":"andrewleech","email":"andrew@alelec.net"}],"description":"MCP server for controlling ViperIDE, a MicroPython/CircuitPython IDE. Connects to devices via USB serial, manages files, executes code, and provides full REPL access.","homepage":"https://viper-ide.org","keywords":["mcp","micropython","circuitpython","ide","viperide","serial","repl","embedded"],"repository":{"type":"git","url":"git+https://github.com/andrewleech/ViperIDE.git","directory":"mcp"},"bugs":{"url":"https://github.com/andrewleech/ViperIDE/issues"},"license":"MIT","readme":"# ViperIDE MCP Server\n\nAn MCP (Model Context Protocol) server that gives Claude full remote control of [ViperIDE](https://viper-ide.org), a MicroPython/CircuitPython IDE. The IDE opens in your browser for direct interaction while Claude simultaneously controls it via MCP tools.\n\n## Architecture\n\nThe MCP server acts as a bridge between Claude and ViperIDE running in your browser. It also provides a serial-to-WebSocket bridge so USB devices can be connected without browser permission dialogs.\n\n| Component | Role | Connection |\n|---|---|---|\n| **Claude** (Code/Desktop) | Sends MCP tool calls | stdio JSON-RPC to MCP server |\n| **MCP Server** (Node.js) | Routes commands, serves IDE, bridges serial | localhost HTTP + WebSocket |\n| **Browser** (ViperIDE) | IDE UI, executes commands on device | WS control channel (`/ws`) |\n| **USB Device** (MicroPython) | Target hardware | Serial port via WS bridge (`/serial/...`) |\n\nThe MCP server:\n1. Serves the built ViperIDE on a random localhost port\n2. Opens your default browser to the IDE\n3. Maintains a WebSocket control channel for sending commands\n4. Exposes IDE operations as MCP tools that Claude can call\n\nBoth you and Claude can interact with the IDE simultaneously.\n\n## Install\n\n### Claude Desktop\n\nDownload the `.mcpb` bundle for your platform from [Releases](https://github.com/andrewleech/ViperIDE/releases). In Claude Desktop, go to Settings > Extensions > Advanced Settings > Install Extension, then select the `.mcpb` file.\n\n### Claude Code\n\n```bash\nclaude mcp add viperIDE -- npx -y @andrewleech/viperide-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/andrewleech/ViperIDE.git\ncd ViperIDE && npm install && python3 build.py\ncd mcp && npm install\nclaude mcp add viperIDE -- node $(pwd)/src/index.js\n```\n\n## Available Tools\n\n### Connection\n| Tool | Description |\n|---|---|\n| `viperIDE_get_status` | Connection status, device info, open file, editor state |\n| `viperIDE_connect_device` | Connect via WebSocket (`ws`), virtual device (`vm`), or prompt user for USB/BLE |\n| `viperIDE_connect_serial` | Connect to a USB serial MicroPython device via the local WebSocket bridge |\n| `viperIDE_list_serial_ports` | List available USB serial ports with device details |\n| `viperIDE_disconnect_device` | Disconnect current device |\n\n### File Operations (on device)\n| Tool | Description |\n|---|---|\n| `viperIDE_list_files` | List all files and directories with sizes |\n| `viperIDE_read_file` | Read file content |\n| `viperIDE_write_file` | Write content to file (creates parent dirs) |\n| `viperIDE_delete_file` | Delete a file |\n| `viperIDE_delete_dir` | Delete a directory |\n| `viperIDE_mkdir` | Create a directory |\n| `viperIDE_create_file` | Create a new file and open it in the editor |\n\n### Editor\n| Tool | Description |\n|---|---|\n| `viperIDE_open_file` | Open a device file in the editor |\n| `viperIDE_get_editor` | Get current editor content and filename |\n| `viperIDE_set_editor` | Replace editor content |\n| `viperIDE_save_file` | Save editor content to device |\n\n### Execution\n| Tool | Description |\n|---|---|\n| `viperIDE_run_file` | Run current file on device (non-blocking) |\n| `viperIDE_stop` | Interrupt running script (Ctrl-C) |\n| `viperIDE_reboot` | Reboot device (soft/hard/bootloader) |\n\n### Terminal\n| Tool | Description |\n|---|---|\n| `viperIDE_read_terminal` | Read REPL output |\n| `viperIDE_write_terminal` | Send input to REPL |\n| `viperIDE_clear_terminal` | Clear terminal |\n\n### Packages\n| Tool | Description |\n|---|---|\n| `viperIDE_install_package` | Install a MicroPython package by name or URL |\n\n## USB Serial Bridge\n\nThe MCP server includes a serial-to-WebSocket bridge that lets Claude connect directly to USB serial MicroPython devices without requiring the browser's WebSerial permission picker.\n\n1. Use `viperIDE_list_serial_ports` to discover connected devices\n2. Use `viperIDE_connect_serial` with the device path to connect\n\nThe bridge opens the serial port at 115200 baud and fakes a WebREPL handshake so ViperIDE's existing WebSocket transport works unchanged. Multiple devices can be bridged simultaneously.\n\nRequires the `serialport` npm package (installed automatically with `npm install`).\n\n## Limitations\n\n- **Bluetooth connections** require the user to click the connect button in the browser (browser security policy requires a user gesture for device picker dialogs).\n- **USB connections** can be made via the serial bridge (`viperIDE_connect_serial`) without user interaction, or via the browser's WebSerial API which requires a user gesture.\n- **WebSocket and VM connections** can be initiated fully by Claude.\n- Running scripts is fire-and-forget. Use `read_terminal` to monitor output and `stop` to interrupt.\n- Only one browser tab should be connected to the MCP server at a time.\n\n## Development\n\nDuring development, you can run the MCP server directly:\n\n```bash\n# Build ViperIDE first\nnpm install && python3 build.py\n\n# Install MCP deps\ncd mcp && npm install\n\n# Run the server (logs to stderr, MCP protocol on stdio)\nnode mcp/src/index.js\n```\n\nThe server picks a random port and opens the browser automatically.\n","readmeFilename":"README.md","_rev":"1-63c25f66921624be1251ba436eb47ccc"}