craftos-mcp
Test ComputerCraft (CC:Tweaked) Lua programs without Minecraft. An emulator with the world around the computer: touch monitors, rednet between computers, turtles, and peripherals from Create, Mekanism and Advanced Peripherals. Agents write, run, test and screenshot programs.
Tài liệu
craftos-mcp
Minecraft 1.18.2 is complete. 1.20.1 is partly there: pick it and you get CC:Tweaked 1.121.0's behaviour and 1.20.1 turtle data, but the mods' peripherals still behave like their 1.18.2 versions for now. 1.21.1 is next. See Choose your Minecraft version.
Let your coding agent test the ComputerCraft code it writes. AI agents write CC:Tweaked Lua they have never run, and the bugs turn up on your server. craftos-mcp is a CC:Tweaked emulator the agent drives itself over MCP: it runs the program, reads the terminal and every monitor, taps buttons, changes the world around the computer (a player walks up, a chest fills, a train arrives, a reactor heats up, an hour passes), writes and runs tests, and fixes what broke until it works. All without Minecraft.
{
"mcpServers": {
"craftos": { "command": "npx", "args": ["-y", "craftos-mcp", "serve"] }
}
}
That one entry works in Claude Code, Cursor, VS Code and any other MCP client; the first start downloads the engine and builds the ROM by itself. The world it simulates is what CC programs depend on: several computers on modems with real rednet, turtles in a block world, and peripherals from Create, Mekanism, Advanced Peripherals and more.
No agent? The same emulator works for people too:
- In a window, like CraftOS-PC:
craftos-mcp window(Without an AI agent). - In your browser:
craftos-mcp appopens computers, monitors and the world side by side. - From the command line and CI:
craftos-mcp test tests/runs your*.test.luafiles.
The engine passes 1190 of 1191 of CC:Tweaked's own tests at 1.101.3 (and 1362 of 1363 at 1.121.0), and the ROM is built from the real CC:Tweaked jar. How exact is it says, area by area, what was measured in game and what was written from source.

A real Claude Code session, unscripted: asked for a door controller with tests, it ran its program in the emulator, caught a monitor that never stopped redrawing and a player at the range edge who could not get in, fixed both, and finished with its tests passing. The full transcript is next to the video.
Some games built and tested with it are playable in your browser, no install, and there's a highlight reel of them.
What it does
- Run and test: run a program in a fresh computer and get the terminal and every monitor back as text, PNGs or
golden snapshots; run
*.test.luafiles with the built-inccunitharness. - Interactive sessions: type, press keys, touch monitors, send events, wait for text.
craftos_uireads every screen as buttons and text runs with colours, so an agent can drive a UI without screenshots. - Monitors at any wall size and text scale, with real touch events.
- Several computers at once: wireless, ender and wired modems with real rednet, ranges and wired names.
- Turtles in a block world built from vanilla 1.18.2 data: the whole turtle API with its tick timing, digging with loot-table drops, placing, inventories, refuelling, upgrades and crafting. What a turtle places comes alive: computers boot, disk drives take floppies, monitors join into walls.
- CC's generic peripherals: chests, barrels and any modded block as an inventory, fluid tank and energy store,
with
pushItems,pullItems,pushFluidand levels that move over time. - Peripherals from other mods, written from each mod's source and checked against its jar, each one an addon
you switch on only if your pack has it (see Choose your mods):
- Advanced Peripherals 0.7.31r: player, energy and environment detectors, chat box, redstone integrator, NBT storage, AR controller, ME and RS bridges.
- Mekanism 10.2.5: QIO, the Quantum Entangloporter, the boiler and induction matrix; with Mekanism Generators, the fission reactor, turbine and fusion reactor, running tick by tick (a reactor left alone melts down).
- Create 0.5.1: train stations with schedules and trains on the clock, gauges, speed controllers, sequenced gearshifts and the display link; Create Crafts & Additions 1.0.0's motor, accumulator, relay and digital adapter.
- Tom's Peripherals 1.2.1: the GPU with its full drawing API, pixel-exact and in screenshots, keyboard, redstone port and watchdog.
- Bigger Reactors 0.6.0 and Extreme Reactors 2.0.71: reactors and turbines with their real heat, fuel and rotor physics.
- Determinism: seed
math.random, run the clock faster, or jump it forward so timers fire instantly. - Your way in: a desktop window, a browser app (also the MCP server's live viewer at http://127.0.0.1:7878),
a command line, and an in-computer
simcommand to change the world by typing (sim join Alice).
Games
Three game cabinets in plain CC:Tweaked Lua, each with a world file and tests that play real games through taps on the monitors. They're examples of what you can build and test here, and they use nothing but CC:Tweaked's own APIs.
| Cabinet | Games | Shows off |
|---|---|---|
| Board | Ultimate Tic-Tac-Toe, Four in a Row, Reversi, Checkers, Dots and Boxes, Mancala, Fleet, Codebreaker; three computer levels | touch monitor walls, two players at one wall |
| Action | Snake, Blocks, Bricks, Lander, Mines | fast redraws, real-time touch |
| Versus | Paddle, Trails, Artillery | two computers in one match over rednet |
![]() | ![]() |
| Blocks, steered by tapping the wall | Paddle across two computers on rednet (3x speed) |
Each cabinet's README says how to open it. The board games, for example:
craftos-mcp window workspace/examples/games/board/arcade.world.json --dir workspace --monitor left:6x6 --monitor right:6x6
# then, in the computer: examples/games/board/arcade
node scripts/make-showcase.mjs records the videos again from real runs.
Examples
workspace/examples/ also has complete programs for the mods above, each with a world
and a test that proves it works: a Mekanism reactor controller, a Create train departure board, an energy monitor for
any modded battery, a Tom's Peripherals GPU demo, an Extreme Reactors rod controller, an Advanced Peripherals player
greeter and a rednet chat between two computers. These pictures are rendered from real runs (node scripts/make-demo-gif.mjs makes them again).

The reactor controller on a simulated Mekanism reactor, with the clock sped up: it scrams the reactor before it is damaged, and RESET restarts it once it has cooled. The test checks exactly that.
![]() | ![]() |
| Train departure board: platform, train, status and schedule for each station | GPU demo: a spinning cube, a sine ribbon and ripples where you right-click |
![]() | ![]() |
| Power monitor: any block with an energy store, with rates and a low-power alarm | The reactor controller after it has scrammed on temperature |
Setup
You need Node.js 22 or newer.
From npm (Windows and Linux x64)
npx -y craftos-mcp serve # the MCP server, for any agent
claude mcp add craftos -- npx -y craftos-mcp serve
npx craftos-mcp test # or window, app, run, info: see the command line below
The package holds no engine or ROM. The first command fetches the engine from this repository's release, builds the
ROMs from the real CC:Tweaked jars and the GPU fonts, and keeps them in %LOCALAPPDATA%\craftos-mcp or
~/.cache/craftos-mcp (CRAFTOS_HOME moves it); that takes a few seconds to a minute, once per version. serve
answers its client straight away and lets the tools that run computers wait for it. The workspace is the folder you
run it in. craftos-mcp setup --force does the setup again.
Quick start from a clone
git clone https://github.com/Akkiruk/craftos-mcp
cd craftos-mcp
npm run setup
npm run setup installs the packages, builds the tools, builds the ROM from the real CC:Tweaked jar (and Tom's
Peripherals' fonts), downloads the prebuilt engine for your OS from the latest release, checks everything and prints
the line that connects your agent. Run it again any time: finished steps are skipped. If the release has no engine for
your OS it tells you how to build one (below).
Claude Code plugin
One install gives Claude Code the cc-tweaked-dev skill and the craftos MCP server:
/plugin marketplace add Akkiruk/craftos-mcp
/plugin install craftos-mcp@craftos-mcp
Claude Code keeps a copy of this repository for the plugin, which has no engine or ROM yet, so the first time the
server starts it runs the setup above in the background (a few minutes: it downloads the jar and the engine). If
/mcp shows the server as failed on that first try, wait a minute and reconnect; setup carries on without it. Progress
is in .cache/setup.log inside the plugin's folder. The plugin asks which mods your pack has (the addon list below),
and the server's workspace is the folder you start Claude Code in.
The command line
craftos-mcp runs without an agent, so it works in scripts and CI. Run it from your Lua project folder (--dir
changes that):
craftos-mcp test # every *.test.lua below here, ccunit harness; exits 1 on a failure
craftos-mcp test tests/ --addons create --timescale 10
craftos-mcp run clock.lua --monitor top:2x2 --screenshot shot.png # terminal and monitors as text, PNGs saved
craftos-mcp run sort.lua --world worlds/chests.json --timeout 20 -- --verbose
craftos-mcp info # engine, ROM and addons status
craftos-mcp serve # the MCP server over stdio
Inside a clone use npx craftos-mcp ..., or node apps/cli/dist/index.js .... craftos-mcp help <command> lists the
options. A --world is a JSON file or the name of one in worlds/; --addons is all, none or ids separated by
commas.
Doing it by hand
1. The engine
Download the prebuilt engine for your OS from the latest release and unzip it over the repository, or build it yourself:
- Windows: Visual Studio 2022 (or its Build Tools) with C++, CMake, Ninja and a vcpkg
checkout in
VCPKG_ROOT. Thenengine\build.cmd. - Linux: a C++17 compiler, CMake, Ninja and vcpkg in
VCPKG_ROOT. Thenengine/build.sh.
macOS is not supported yet.
2. The ROM
CC:Tweaked's license does not allow its ROM to be redistributed with this project, so you build it on your own
machine. This downloads CC:Tweaked 1.101.3 from Modrinth, checks its hash, and builds rom/cc-1.101.3:
node scripts/build-rom.mjs --download
If you already have the jar: node scripts/build-rom.mjs path/to/cc-tweaked-1.18.2-1.101.3.jar rom/cc-1.101.3.
The same step downloads Tom's Peripherals 1.18.2-1.2.1 (MIT) and builds the GPU's fonts from it, since they are not
shipped here either (node scripts/build-toms-fonts.mjs does it alone).
3. The tools
npm install
npm run build
4. Connect your agent
Claude Code:
claude mcp add craftos -- node /path/to/craftos-mcp/apps/mcp-server/dist/index.js
VS Code: .vscode/mcp.json is already set up for this folder. Other MCP clients: run
node apps/mcp-server/dist/index.js over stdio. Then call craftos_info; it lists anything that is missing.
Point CRAFTOS_WORKSPACE at your own Lua project to work on it in place. Other settings: CRAFTOS_ENGINE,
CRAFTOS_ROM, CRAFTOS_RUNTIME_ROOT, CRAFTOS_VIEWER_PORT (off turns the viewer off).
Without an AI agent
craftos-mcp window opens the computer in a desktop window, with the same simulated world an agent gets:
craftos-mcp window worlds/generic-storage-demo.json --monitor top:3x2 # from your Lua project folder
craftos-mcp window create-demo --dir path/to/project # a world from worlds/ by name
The computer's files are your folder (--dir, default the current one), live: edit in your own editor, then hold
Ctrl+R in the window to reboot. Monitors open as windows of their own and a click is a touch; a world can list them
under "monitors". A world's speakers play real sound. F12 copies a screenshot to the clipboard. Turtle worlds and several computers on
one network do not open in a window yet.
Inside the computer, the sim program changes the world, as craftos_sim_command does for an agent. It is the
emulator's own: a real CC:Tweaked computer has no sim.
sim join Alice sim leave Alice
sim chat Alice hello sim advance 60 (jump the clock 60 seconds)
sim item chest_0 1 minecraft:diamond 5
sim state (players, peripherals, chat)
sim createTrainArrive station=Create_Station_0 train=Express (any command a mod's simulation knows)
sim help (all of them)
In your browser
craftos-mcp app starts a local web page and opens it:
craftos-mcp app --dir path/to/project # --port 7878 by default; --no-open just prints the address
New computer makes one: a normal, advanced, pocket or turtle computer, a world from worlds/ or your own JSON,
the mods your pack has, monitors and their sizes, and a program to run (or just the shell). Set Computers above 1
for a network, each with a modem. Every computer gets a tab. Its terminal takes the keyboard, paste and mouse; the
Ctrl+T, Ctrl+R and Ctrl+S buttons hold the keys for a second as CC needs (your browser keeps Ctrl+T for itself).
Monitors and Tom's Peripherals GPU screens update live, and a click is a touch on that cell or pixel; UI outlines
what the screens show as buttons. On the side: the world (players join, leave and chat, the clock jumps, items go
into slots, and the whole sim state as a tree), a box for any sim command with the list of the ones this world knows,
and the computer's files, which you can edit, or copy your project in again, and reboot.
It listens on 127.0.0.1 only. The MCP server's live viewer (http://127.0.0.1:7878) is the same page, so you can watch and help while an agent works.
Choose your Minecraft version
| Version | CC:Tweaked | State |
|---|---|---|
1.18.2 (default) | 1.101.3 | Complete: CC itself, turtles, modems and every mod below |
1.20.1 | 1.121.0 | CC itself and turtles (1.20.1 block data) as in 1.121.0; the mods still act as their 1.18.2 versions |
1.21.1 | 1.121.0 | CC itself as in 1.121.0; turtle data and mods not done yet |
Pick one per world with "version": "1.20.1", for the MCP server with CRAFTOS_VERSION, or on the command line with
--mc 1.20.1. Each CC:Tweaked version needs its ROM: node scripts/build-rom.mjs --download 1.20.1, or
npm run setup -- --mc all for every version. A mod that does not exist on the chosen version (Bigger Reactors on
1.21.1) is refused with a message.
Choose your mods
Every mod besides CC:Tweaked is an addon. Switch on only the ones your pack has, so a program cannot come to rely on
a peripheral your server does not have. Set CRAFTOS_ADDONS for the MCP server (the .vscode/mcp.json here lists
them all: delete the ones you do not use), or give one world its own list with addons:
{
"addons": ["create", "mekanism"],
"peripherals": [{ "name": "station_0", "type": "Create_Station" }]
}
| Id | Mod |
|---|---|
advanced-peripherals | Advanced Peripherals 0.7.31r |
mekanism | Mekanism 10.2.5 |
mekanism-generators | Mekanism Generators 10.2.5 (needs mekanism) |
create | Create 0.5.1.i |
create-additions | Create Crafts & Additions 1.0.0 (needs create) |
toms-peripherals | Tom's Peripherals 1.18.2-1.2.1 |
bigger-reactors | Bigger Reactors 1.18.2-0.6.0-beta.1.4 |
extreme-reactors | Extreme Reactors 1.18.2-2.0.71 |
"all" and "none" work too. With no setting at all, everything is on. A world that uses a block from an addon that
is off fails before the computer boots and names the addon; craftos_info lists what is on.
Tools
| Tool | Purpose |
|---|---|
craftos_info | Engine, ROM and workspace status |
craftos_write_file, craftos_read_file, craftos_list_files | Workspace files (copied to the root of each computer) |
craftos_run | Run a program in a fresh computer: terminal and monitor text, PNGs, golden snapshots |
craftos_test | Run *.test.lua files with the ccunit harness |
craftos_session_create, craftos_type, craftos_key, craftos_touch_monitor, ... | Interactive computers |
craftos_ui, craftos_act, craftos_settle, craftos_expect, craftos_script | Read screens as data, act and wait until the program is done, assert |
craftos_network_create, craftos_network_update | Several computers with modems |
craftos_sim_command, craftos_sim_state | Change and read the simulated world during a session |
craftos_seed, craftos_advance, craftos_trace, craftos_screenshot | Determinism, the virtual clock, what the program saw, pictures |
For an agent, .claude/skills/cc-tweaked-dev/SKILL.md is a short guide to using these well.
Your own modpack
The turtle world ships with vanilla Minecraft, Forge and CC:Tweaked data. To give it every block, item, recipe and loot table in your modpack, generate the data from your own instance:
python -I tools/turtledata/extract.py --instance "<your instance>/minecraft"
Layout
engine/ Forked CraftOS-PC 2 (MIT, see engine/UPSTREAM.md)
packages/ rawterm (engine protocol, PNG renderer), runner (runs, tests, sessions, networks, browser app), protocol
apps/ The craftos-mcp command line (window, app, test, run, info, serve) and the MCP server
rom-overlay/ The simulation layered over the CC:Tweaked ROM (peripherals, modems, turtles)
web/ The browser build: the engine as WebAssembly and a player for pages (web/README.md)
scripts/ Setup, ROM builder, CC:Tweaked conformance runner, the video recorder
tools/ Data extraction for turtles
worlds/ Example worlds
docs/ Architecture, security model, peripherals, turtles, conformance
Known limits
- Minecraft 1.18.2 is complete; on 1.20.1 and 1.21.1 the mods are still their 1.18.2 versions (see Choose your Minecraft version). Older versions (1.16.5, 1.12.2) are not supported.
- Only the mods listed above are simulated, and each from its source: where a mechanic is too large to copy (Create's stress network and track graph, multiblock formation) it is a fixture instead. Each mod's doc ends with what is not simulated or not confirmed. Pocket computer upgrades and most of Advanced Peripherals' turtle upgrades are not simulated (the geo scanner and chunky turtle are).
- A pattern that never finishes inside one C function (a pathological
string.find) cannot be aborted by the engine; the runner's timeout ends the process instead. - The virtual clock can run faster, but it is not a fully deterministic scheduler.
- Lua runs in a scratch directory per run, but the engine is not sandboxed by the OS. Only run code you trust; see docs/security.md.
Credits
The engine is a fork of CraftOS-PC 2 by JackMacWindows (MIT). CC:Tweaked is by SquidDev and contributors; this project does not include it, and builds its ROM on your machine from the official jar. Not affiliated with Mojang or Microsoft.
License
MIT, see LICENSE. The engine keeps CraftOS-PC's MIT license (engine/LICENSE). See NOTICE.md for third-party parts.





