computercraft-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@computercraft-mcp run lua to print the turtle's inventory and fuel level"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
computercraft-live-mcp
Live, in-world control of ComputerCraft: Tweaked computers for AI assistants. Let an AI assistant (Claude Code, or any MCP client) work on a real computer inside a running Minecraft world: run Lua, read and write files, call peripherals, and see every error, including from programs a player started by hand.
What this is
The real computer, not a model of it. Every call runs on a computer in your actual world or server, with your real mods, peripherals, config and timing. Nothing is emulated.
Built for operating and debugging. Fix a broken program on a live base, inspect a wired-modem network, read what a player's program just printed, push a file to a computer, or watch a script misbehave in the conditions where it actually runs.
Shared with the players. The computer's own shell keeps working. The AI and a player can use the same machine, and the AI sees errors from programs the player launched.
Nothing to build or maintain. A small Python relay and one Lua file. There is no ROM to build and no per-mod modelling to keep up with, so new mods and CC:Tweaked releases work as soon as they run in your game.
It needs a running Minecraft world with CC:Tweaked. It does not run ComputerCraft programs outside the game.
MCP client --stdio--> computercraft-live-mcp --HTTP + API token--> relay <--outbound websocket-- bridge.lua (in-game computer)The in-game computer connects out to a small relay on your machine, so nothing needs to be exposed to the internet and the computer's own shell keeps working for players.
Related MCP server: Roblox Executor MCP Server
Tools
tool | what |
| run Lua (persistent session, returns values, terminal output and errors) |
| run a shell command / program |
| files on the computer (paged reads, append) |
| upload / download files between your disk and the computer (opt-in, see below) |
| list peripherals (grouped by type, with methods, across wired modems) |
| call peripheral methods; a batch can run in parallel in one game tick |
| recent terminal text plus every |
| which computers are connected, liveness, stop a stuck request |
Errors come back as data: an ERROR line, error.kind, message, traceback, hints for known causes and any printError output.
Computer data (file contents, output, log lines, labels, peripheral names, error messages) comes back inside <untrusted source="..." id="..."> ... </untrusted id="..."> blocks with a random id, so it cannot pose as the server's own lines. ccctl has a subcommand for every tool and prints the same text; add --json for the raw result.
Quick start
pip install git+https://github.com/slashracer5/computercraft-live-mcp # or: uv tool install git+https://...
computercraft-live-mcp-relay --setup # starts nothing; prints the in-game commands with your token
computercraft-live-mcp-relay # run the relay (leave it running)In CC:Tweaked's server config, allow the relay (rule goes above the default
$privatedeny), then restart the world:[[http.rules]] host = "127.0.0.1" port = 8765 action = "allow"On the in-game computer, type the commands
--setupprinted (wget .../bridge.lua bridge.lua, thenbridge ws://127.0.0.1:8765/ws <token>).Register the MCP server with your client. For Claude Code, copy
examples/mcp.json.exampleto.mcp.jsonand setCC_MCP_FILES_ROOT.
Full walkthrough, troubleshooting and the protocol reference: docs/QUICKSTART.md, docs/REFERENCE.md.
Configuration
variable | default | meaning |
|
| relay address used by the MCP server and |
|
| folder holding |
| from | override the tokens |
| (unset: push/pull refuse) | local folder(s) |
Security
This is a remote shell for a game computer. Keep the relay on loopback or a private network, never share tokens.json, and read SECURITY.md before running it anywhere other than your own machine. Anything the computer sends back is untrusted data, and tool results mark it as such.
Development
pip install -e ".[dev]"
ruff check . && ruff format --check .
pytest # everything, incl. the CraftOS-PC end-to-end test if the emulator is found
pytest -m "not e2e" # quick run: unit and relay tests only
python tests/selftest_cc.py # the end-to-end test on its ownThe end-to-end test runs bridge.lua in headless CraftOS-PC (no Minecraft needed). It uses CRAFTOS_PC if set, otherwise %LOCALAPPDATA%\CraftOS-PC\CraftOS-PC_console.exe (Windows), craftos on PATH (Linux) or /Applications/CraftOS-PC.app/Contents/MacOS/craftos (macOS), and is skipped with the reason shown when it finds none. Tests use temporary folders and free loopback ports, never your own tokens or CraftOS-PC data.
CI runs ruff and pytest on Python 3.10–3.14 on Linux, Windows and macOS. Known bugs #1 and #5 have strict xfail regression tests: drop the mark when fixing them.
Tested with Python 3.14, CC:Tweaked on Minecraft 1.21.1 (NeoForge) and CraftOS-PC. MIT licensed.
Available Tools
15 toolscc_batchA
Run many peripheral calls in one request. calls = [{"peripheral": "ship_...", "method": "getSpeed",
"args": []}, ...]. With parallel=True (default) they run concurrently, so N reads cost one game tick instead
of N (use for sensor sweeps and control-loop style reads/writes). Each call reports its own result or error.
Inputs: calls (required), timeout, computer, parallel. Returns: result
cc_callA
Call one peripheral method and return its result(s): peripheral.call(name, method, *args).
args is a JSON list (numbers, strings, booleans; objects/arrays become Lua tables). Errors from the
peripheral (wrong argument, bad enum value) come back as data. Getters are safe; setters, assemble/disassemble
and similar change the live world - ask first. Setters wait for the next game tick (game must be focused).
Inputs: method (required), peripheral (required), args, timeout, +1 more. Returns: result
cc_cancelA
Abort the request that is currently running on the computer (for a hung or runaway cc_exec/cc_shell).
Inputs: computer. Returns: result
cc_computersARead-only
List the in-game computers currently connected to the relay (id, label, game version).
Inputs: no named parameters. Returns: result
cc_execA
Run Lua on the computer and return its output, return values and any error.
code may be an expression (os.getComputerID()) or statements. Variables persist between
calls until reset=True. Syntax errors, runtime errors (with traceback), printed text and
printError lines all come back. A script that never yields is aborted by CC after ~7 s.
Inputs: code (required), reset, timeout, computer. Returns: result
cc_listCRead-only
List a directory on the computer (names, whether each is a directory, sizes).
Inputs: path, computer. Returns: result
cc_logARead-only
Show the computer's terminal history and unattended-error log.
lines of recent terminal text (lines marked ! were red), plus every printError message with an
id. This is how errors from programs started by hand (or by other code), not through these tools, show up.
Pass since_error=<last_error_id from the previous call> to see only new errors; errors_only=True
skips the terminal text.
Inputs: lines, computer, errors_only, since_error. Returns: result
cc_networkBRead-only
Inventory every peripheral the computer can see (directly attached, on wired-modem networks, and the
Create Avionics / Sable ship_* bridge), grouped by type, plus modem info and whether the computer is on a
Sable ship (and its mass). methods=True also lists each group's method names once.
Names in the output are exactly what to pass to cc_call / cc_batch / peripheral.call. Read-only.
Inputs: methods, computer. Returns: result
cc_peripheralsBRead-only
List attached peripherals (name and type); methods=True also lists each one's method names.
Inputs: methods, computer. Returns: result
cc_pingBRead-only
Check that a computer answers; returns its id, label, uptime (clock), game day and free disk space.
Inputs: computer. Returns: result
cc_pullB
Download a computer file (text/CSV/log; large files are paged automatically) into a local folder. Overwrites the local file. Only the folders listed in CC_MCP_FILES_ROOT are allowed.
Inputs: local_path (required), remote_path (required), computer. Returns: result
cc_pushA
Upload a local UTF-8 text file to the computer, chunked automatically; overwrites unless append=True. Relative local paths are taken from the first folder in CC_MCP_FILES_ROOT; only the folders listed there are allowed. Use this to deploy programs instead of pasting their source through cc_write.
Inputs: local_path (required), remote_path (required), append, computer. Returns: result
cc_readARead-only
Read a file from the computer (up to ~60 KB per call; page with offset when told more remains).
Inputs: path (required), offset, computer. Returns: result
cc_shellB
Run a shell command or program (ls, edit-less programs, myprogram arg) and return its output.
A failing program returns ERROR with the message and its printError output in stderr.
Interactive programs that wait for keys will time out.
Inputs: command (required), timeout, computer. Returns: result
cc_writeA
Write (or append to) a file on the computer. Text is sent as UTF-8; keep each call under ~100 KB and use append=True for larger files. Overwrites without asking.
Inputs: path (required), content (required), append, computer. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools target a distinct action/resource (exec Lua vs shell command, call vs batch, push vs pull), and descriptions clarify the boundaries. Two pairs overlap somewhat: cc_peripherals vs cc_network (both enumerate peripherals, one direct-only, one networked) and cc_write vs cc_push (both write remote files, inline vs local upload). These are resolvable from descriptions but still invite occasional misselection.
All names use a uniform lowercase snake_case with the `cc_` prefix, which is highly predictable. Minor deviation is that some are action verbs (exec, ping, cancel, read) while others are resource nouns (computers, peripherals, network, log), though this remains readable and consistent in style.
15 tools sits at the upper edge of the well-scoped range for a ComputerCraft relay bridge. Each tool covers a genuinely distinct capability (discovery, execution, file transfer, peripheral I/O, logs, cancellation), though the file-transfer and peripheral-inventory tools could arguably be consolidated.
The surface covers discovery, code/shell execution, file read/write plus local push/pull, peripheral inspection and batch calling, logging, and cancellation — a solid lifecycle for the domain. Gaps remain: no file delete/move or directory creation, and no explicit reboot/shutdown/reset-computer operation beyond cc_exec's reset flag.
Maintenance
Related MCP Connectors
Connect AI assistants to explicitly paired computers, servers, and VMs for permitted remote actions.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- AlicenseCqualityDmaintenanceAllows AI assistants to connect to and control Minecraft players on remote servers, enabling navigation, building, mining, inventory management, entity interaction, and chat communication through natural language commands.2711 npm13MIT
- AlicenseAqualityBmaintenanceEnables AI agents to execute Lua code, inspect scripts, spy on remotes, and interact with a running Roblox game client through an MCP interface.162266 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to validate and run Minecraft commands, read chat and tellraw messages, control player movement and GUI, and capture screenshots from within the game, aiding datapack debugging.1MIT
- AlicenseAqualityBmaintenanceEnables AI agents to drive a running Roblox Studio in real time over a single WebSocket, executing whole Luau programs, installing in-engine controllers, hot-patching scripts during live playtests, and receiving errors, assertions and other events as pushes. It also reaches Roblox Open Cloud for the open place and answers visual questions via a vision sidecar, exposing all of this through nine MCP tools.92MIT