Skip to content
Back to search

driveblox

Drive Roblox Studio from the shell or Python through its built-in MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tdotlab--driveblox/badge.svg)](/listings/tdotlab--driveblox)

HTML

<a href="/listings/tdotlab--driveblox"><img src="/api/listings/tdotlab--driveblox/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pipx install git+https://github.com/tdotlab/driveblox

or `pip install git+https://github.com/tdotlab/driveblox`, or clone and `pip install -e .`.

Then turn the server on inside Studio: Assistant, then the menu, then Manage MCP Servers, then enable **Enable Studio as MCP server**. Keep Studio open with a place loaded. With the toggle off, the proxy gets a 401 and publishes no tools; driveblox says so and tells you where the switch is.

Check the whole chain:

$ driveblox doctor --input
[ok] find the MCP proxy
[ok] start the proxy
[ok] list tools: 39 tools
[ok] find an open Studio
[ok] read Studio state
[ok] run Luau in the Edit datamodel: 2
[ok] keystroke reaches the game
all good

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 165 lines
  1. # driveblox
  2. Drive Roblox Studio from the shell or from Python. It speaks to the MCP server that Studio now ships with, so you can start a playtest, run Luau, press keys, walk a character around, wait on game state and read the console, all from a command line or a script, with no MCP client in the way.
  3. ```console
  4. $ driveblox play start
  5. $ driveblox nav 12 3 -5
  6. $ driveblox key hold e 1.2
  7. $ driveblox wait "workspace.Diner:GetAttribute('Stage') == 'served'" --timeout 12
  8. $ driveblox console --grep error
  9. $ driveblox play stop
  10. ```
  11. Zero dependencies. Python 3.9 or newer. MIT licensed. Not affiliated with or endorsed by Roblox.
  12. ## Why this exists
  13. Studio's built-in MCP server is fine if your agent speaks MCP. Plenty of setups do not: a shell-only agent, a CI job, a script you wrote by hand, an editor whose integration list is short. Driveblox puts a command line in front of the same server, and it adds three things the raw tools do not give you.
  14. One process, many steps. Every MCP call from a chat agent is a model round trip. A script that holds a connection open does thousands of calls without one, which is the difference between a test that can catch a 2.5 second tip window and one that cannot. `driveblox batch` and the Python API both run everything over a single connection.
  15. State sync instead of sleeping. `driveblox wait` polls a Luau expression until it is truthy, so a script waits for the game to be ready rather than guessing how long that takes.
  16. A fix for the silent input failure, which deserves its own section.
  17. ## The input gotcha (read this)
  18. Studio's input tools (`user_keyboard_input`, `user_mouse_input`, `character_navigation`) return "Success" even when the game never received the input. During a playtest the game only gets keys once its viewport has real operating system window focus. After a fresh playtest, a click elsewhere in Studio, or switching apps, focus can be lost, and then your script runs cleanly and does nothing at all.
  19. Driveblox deals with this in two ways. `driveblox doctor --input` starts a playtest, listens for a key inside the game, sends one, and tells you whether it arrived. On Windows, `driveblox focus` (or `driveblox play start --focus`) clicks inside the Studio window to restore focus. It moves your real mouse cursor, so do not use the mouse while it runs. Elsewhere, click once inside the game viewport yourself before the script starts.
  20. ## Install
  21. ```console
  22. pipx install git+https://github.com/tdotlab/driveblox
  23. ```
  24. or `pip install git+https://github.com/tdotlab/driveblox`, or clone and `pip install -e .`.
  25. Then turn the server on inside Studio: Assistant, then the menu, then Manage MCP Servers, then enable **Enable Studio as MCP server**. Keep Studio open with a place loaded. With the toggle off, the proxy gets a 401 and publishes no tools; driveblox says so and tells you where the switch is.
  26. Check the whole chain:
  27. ```console
  28. $ driveblox doctor --input
  29. [ok] find the MCP proxy
  30. [ok] start the proxy
  31. [ok] list tools: 39 tools
  32. [ok] find an open Studio
  33. [ok] read Studio state
  34. [ok] run Luau in the Edit datamodel: 2
  35. [ok] keystroke reaches the game
  36. all good
  37. ```
  38. ## Commands
  39. Everything prints plain text or JSON to stdout, errors to stderr, and uses a small set of exit codes (below). Run `driveblox <command> --help` for details.
  40. | Command | What it does |
  41. | --- | --- |
  42. | `doctor [--input]` | Check proxy, connection, Luau round trip; with `--input`, prove a keystroke reaches the game |
  43. | `studios`, `state`, `tools`, `schema TOOL` | See what is connected and what Studio offers |
  44. | `play start\|stop [--focus]` | Start or stop Play Solo, waiting until both Client and Server datamodels exist |
  45. | `lua [-d edit\|client\|server] [-c CODE \| FILE \| -]` | Run Luau and print the result |
  46. | `wait EXPR [-d DM] [--timeout S] [--interval S]` | Poll a Luau expression until truthy |
  47. | `key press K...`, `key hold K SECONDS`, `key type TEXT`, `key seq "down:W wait:800 up:W"` | Keyboard input in the playtest |
  48. | `click X Y [--right]`, `click --path PATH` | Mouse click by position or by GuiObject path |
  49. | `nav X Y Z [--speed N]`, `nav --path PATH` | Walk the character somewhere and wait until it arrives |
  50. | `console [-n N] [--grep RE]` | Studio output log |
  51. | `tree`, `inspect` | Walk the instance tree, read an instance's properties |
  52. | `shot FILE` | Edit-time viewport screenshot |
  53. | `call TOOL '{json}'` | Call any MCP tool directly |
  54. | `batch FILE\|-` | Run many commands over one connection |
  55. | `focus [X Y]` | Windows: click the viewport so it has input focus |
  56. Input commands act on the Client datamodel, so run `play start` first.
  57. ### Batch
  58. A batch file is one command per line, `#` for comments. They run in order over one connection and stop at the first failure unless you pass `--keep-going`.
  59. ```
  60. play start --focus
  61. wait "game.Players.LocalPlayer.Character ~= nil" -d client --timeout 30
  62. nav 0 3 10
  63. key hold e 1.2
  64. wait "workspace.Diner:GetAttribute('Stage') == 'cooked'" --timeout 12
  65. console --grep error
  66. play stop
  67. ```
  68. ```console
  69. $ driveblox batch playthrough.batch
  70. ```
  71. ### Python
  72. ```python
  73. from driveblox import Studio
  74. with Studio() as s:
  75. s.play(True, focus=True)
  76. s.wait_for("#game.Players:GetPlayers() == 1", dm="server")
  77. s.nav(12, 3, -5)
  78. s.hold("e", 1.2)
  79. s.wait_for("workspace.Diner:GetAttribute('Stage') == 'cooked'", timeout=12)
  80. print(s.lua("return workspace.Diner:GetAttribute('Cash')", dm="server"))
  81. s.play(False)
  82. ```
  83. `examples/` has a smoke test that works on any place, and a full scripted playthrough of a small diner game that shows the pattern: no screenshots, sync on attributes the server publishes, one connection start to finish.
  84. ## Exit codes
  85. | Code | Meaning |
  86. | --- | --- |
  87. | 0 | OK |
  88. | 1 | A Studio tool reported an error, or a `wait` timed out |
  89. | 2 | Usage or protocol error |
  90. | 3 | Studio not reachable: not running, MCP toggle off, or proxy not found |
  91. ## Environment
  92. | Variable | Effect |
  93. | --- | --- |
  94. | `DRIVEBLOX_MCP_CMD` | Command that starts the MCP proxy, as a JSON array or a plain command line. Overrides discovery |
  95. | `DRIVEBLOX_STUDIO` | Studio instance id when several are open (or use `--studio`, `--place`) |
  96. | `DRIVEBLOX_CONNECT_TIMEOUT` | Seconds to wait for Studio to connect (default 25) |
  97. ## Platform status
  98. I want this to be straight with you, because only one of these has actually been run.
  99. Windows is tested against a live Studio: the doctor, the batch runner, the input checks and a full scripted playthrough. Driveblox looks for `StudioMCP.exe` under `%LOCALAPPDATA%\Roblox\Versions` and takes the newest. Roblox's own `mcp.bat` points at a hardcoded version folder and goes stale after updates, which is why it is only a fallback.
  100. macOS is written from Roblox's documentation (`/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP`) and has not been run. The test suite does run on macOS in CI, against a fake server.
  101. Linux has no native Studio. The only route is Wine, usually through Vinegar, and whether Studio's built-in MCP server works there is unverified. Driveblox searches the usual Vinegar and Wine prefixes for `StudioMCP.exe` and launches it with `wine`. If it misses, point it at the right place:
  102. ```console
  103. export DRIVEBLOX_MCP_CMD='["wine", "/path/to/prefix/drive_c/users/me/AppData/Local/Roblox/Versions/version-xxxx/StudioMCP.exe"]'
  104. export WINEPREFIX=/path/to/prefix
  105. driveblox doctor
  106. ```
  107. Studio on a different machine than the agent is the more realistic setup for a Linux or headless agent: the proxy talks to Studio over localhost, so driveblox has to run on the machine that runs Studio. Have the agent reach it over SSH, for example `ssh my-windows-box driveblox play start`, or run whole batch files there. This is untested, and one caveat is certain: a non-interactive SSH session has no desktop, so `driveblox focus` and real input focus will not work from it. Check with `driveblox doctor --input` over that same SSH route before trusting any input script.
  108. `driveblox focus` is Windows-only. On X11 you can try restoring viewport focus with xdotool, for example `xdotool search --name "Roblox Studio" windowactivate --sync click 1`, then confirm with `driveblox doctor --input`. If you get Linux working, a note on what you did would be very welcome (see Contributing).
  109. ## Security
  110. Anything that can talk to Studio's MCP server can read and modify the place you have open, and run arbitrary Luau in it. The server is local to your machine and gated by the toggle in Studio, but treat the toggle accordingly: leave it off when you are not using it, and do not run scripts you have not read. Driveblox adds no network access of its own.
  111. ## For other agents
  112. [docs/for-agents.md](docs/for-agents.md) has a short block you can paste into an `AGENTS.md` or `CLAUDE.md` so a shell-only agent knows how to use this.
  113. ## Contributing
  114. Issues and pull requests are welcome, especially reports from macOS and Linux. Run the tests with `python -m unittest discover -s tests -v`. They use a fake MCP server, so they need no Studio. When you report a platform problem, include the output of `driveblox -v doctor --input`.
  115. ## License
  116. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.