Skip to main content
Glama
computercraft-mcp
by slashracer5

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

cc_exec

run Lua (persistent session, returns values, terminal output and errors)

cc_shell

run a shell command / program

cc_read cc_write cc_list

files on the computer (paged reads, append)

cc_push cc_pull

upload / download files between your disk and the computer (opt-in, see below)

cc_peripherals cc_network

list peripherals (grouped by type, with methods, across wired modems)

cc_call cc_batch

call peripheral methods; a batch can run in parallel in one game tick

cc_log

recent terminal text plus every printError, with ids so you can poll only new errors

cc_computers cc_ping cc_cancel

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)
  1. In CC:Tweaked's server config, allow the relay (rule goes above the default $private deny), then restart the world:

    [[http.rules]]
        host = "127.0.0.1"
        port = 8765
        action = "allow"
  2. On the in-game computer, type the commands --setup printed (wget .../bridge.lua bridge.lua, then bridge ws://127.0.0.1:8765/ws <token>).

  3. Register the MCP server with your client. For Claude Code, copy examples/mcp.json.example to .mcp.json and set CC_MCP_FILES_ROOT.

Full walkthrough, troubleshooting and the protocol reference: docs/QUICKSTART.md, docs/REFERENCE.md.

Configuration

variable

default

meaning

CC_MCP_URL

http://127.0.0.1:8765

relay address used by the MCP server and ccctl

CC_MCP_HOME

~/.computercraft-live-mcp

folder holding tokens.json (created on first run)

CC_MCP_API_TOKEN / CC_MCP_COMPUTER_TOKEN

from tokens.json

override the tokens

CC_MCP_FILES_ROOT

(unset: push/pull refuse)

local folder(s) cc_push / cc_pull may touch, separated by ; on Windows and : elsewhere (ccctl uses the paths you type)

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 own

The 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 tools
cc_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_computersA
Read-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_listC
Read-only

List a directory on the computer (names, whether each is a directory, sizes).

Inputs: path, computer. Returns: result

cc_logA
Read-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_networkB
Read-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_peripheralsB
Read-only

List attached peripherals (name and type); methods=True also lists each one's method names.

Inputs: methods, computer. Returns: result

cc_pingB
Read-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_readA
Read-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

    B3.4/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      9
      2
      MIT