Metadata-Version: 2.4
Name: mcusb
Version: 2026.3.6
Summary: USB MCP server — enumerate, inspect, and transfer data with USB devices
Project-URL: Homepage, https://warehack.ing
Project-URL: Repository, https://git.supported.systems/warehack.ing/mcusb
Author-email: Ryan Malloy <ryan@supported.systems>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Hardware :: Universal Serial Bus (USB)
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.14.5
Requires-Dist: pyusb>=1.3.1
Provides-Extra: hotplug
Requires-Dist: pyudev>=0.24.4; extra == 'hotplug'
Description-Content-Type: text/markdown

# mcusb

USB device bridge for [Model Context Protocol](https://modelcontextprotocol.io/) (MCP). Enumerate, inspect, and transfer data with USB devices through structured tools.

Built with [FastMCP](https://github.com/jlowin/fastmcp) and [PyUSB](https://github.com/pyusb/pyusb).

## Install

```bash
pip install mcusb

# With hot-plug detection (Linux, requires libudev):
pip install mcusb[hotplug]
```

Or run directly:

```bash
uvx mcusb
```

## Register with Claude Code

```bash
claude mcp add mcusb -- uvx mcusb
```

## What it does

**23 tools** for working with USB devices:

- **Enumerate** — list devices, view topology
- **Inspect** — descriptors, endpoints, device identification
- **Transfer** — control, bulk, interrupt, and isochronous read/write
- **Manage** — kernel drivers, interface claiming, configuration switching
- **Monitor** — hot-plug event detection via pyudev

**4 resources** for live device data:

- `usb://devices` — connected device list
- `usb://classes` — USB class code reference
- `usb://{device_id}/info` — full descriptor tree
- `usb://events` — hot-plug event buffer

All binary data uses hex string encoding. Device IDs use `bus:addr` format (e.g. `1:2`). Write operations require user confirmation via MCP elicitation.

## Permissions

USB access typically requires either root privileges or a udev rule. The `generate_udev_rule` tool creates persistent rules for specific devices:

```
generate_udev_rule(device_id="1:2")
```

## Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `MCUSB_DEFAULT_TIMEOUT` | `1000` | Transfer timeout (ms) |
| `MCUSB_MAX_TRANSFER_SIZE` | `1048576` | Max bytes per transfer |
| `MCUSB_ALLOW_UNGATED_WRITES` | _(unset)_ | Allow writes without elicitation |
| `MCUSB_HOTPLUG_BUFFER_SIZE` | `50` | Hot-plug event ring buffer size |
| `MCUSB_WATCH_TIMEOUT` | `30` | Default watch_hotplug timeout (s) |

## Requirements

- Python 3.10+
- libusb (system library)
- Linux recommended (udev integration, hot-plug detection)

## License

MIT

## Links

- [warehack.ing](https://warehack.ing)
- [Repository](https://git.supported.systems/warehack.ing/mcusb)
