Check whether this server is talking to Blockbench, the port it listens on, the connection file path and where the tool schemas came from. Call this first when any bb_* tool reports "not connected".

Install or refresh the Blockbench plugin file and print the MCP client configuration for opencode, Claude, Cursor, Windsurf, VS Code, Gemini and Cline. Pass clients:["write"] to actually write the config files.

Drop the current Blockbench connection so the plugin dials back in. Use after reloading the plugin in Blockbench.

Report the connection to the MCP server, the Blockbench version, the open project summary and whether file-system permission has been granted. Call this first in a session.

Run arbitrary async JavaScript inside Blockbench with full access to every global (Project, Cube, Group, Mesh, Texture, Canvas, Codecs, Formats, Modes, Undo, Outliner, Preview, Menu, Action, BarItems, Plugins, StateMemory, ...) and the Node modules a plugin may use. Use this for anything the structured tools do not cover. The code may use await and must return a value; console output is captured and returned. An api argument is injected with helpers: api.find(ref), api.findAll(refs), api.textures(), api.animations(), api.sleep(ms), api.readFile(path), api.writeFile(path,text), api.toBase64(bytes), api.fromBase64(b64), api.toast(text).

Execute a list of tool calls in order inside a single round trip. Each step is {tool, arguments}. Later steps may reference earlier results with "$N.path" (N = step index, or -1/"last" for the previous step), e.g. "$0.element.uuid". Failures are reported per step and do not stop the batch unless stop_on_error is true.

Dump the current project: format, mode, sizes, and optionally the element tree, textures and animations. Call this to re-orient after a large edit.

Change the open project: name, texture resolution, the box_uv default and the view mode. Use it to rename a project or change the texture canvas the model is authored against.

Create a new empty Blockbench project. format is a Blockbench format id (free, java_block, bedrock, bedrock_block, modded_entity, skin, image, ...). Always call this (or bb_open_model) before building, unless a project is already open.

Load a model from disk, replacing the current project (or importing into it). Codec inferred from the extension (.bbmodel, .json, .obj, .gltf, .fbx, .stl, .dae, .jem, .jpm), or set with format (ids from bb_status).

Compile the project to .bbmodel and write it to disk. Without a path, the current project path is reused; pass one to save a copy.

Compile the project into another format and write it to disk. Formats: bbmodel/project, java_block, bedrock, bedrock_old, modded_entity, optifine_entity (jem), optifine_part (jpm), collada (dae), fbx, gltf/glb, obj, stl, skin_model.

Undo the last edit (one or more steps).

Redo the last undone edit.

Switch Blockbench mode: edit, paint, animate, display or pose. Paint/animate are needed for texture and animation tools on some formats.

Change the viewport view mode (textured, solid, wireframe, normal, uv) and/or move the camera to a preset angle (front, back, left, right, top, bottom, isometric_right, isometric_left, true_isometric_right, true_isometric_left, north, east, south, west, up, down). Useful before bb_screenshot.

List runnable Blockbench actions (BarItems) by id and name, optionally filtered.

Trigger any Blockbench action by its BarItems id (see bb_list_actions). This reaches every built-in command the UI exposes.

Show a toast / quick message inside Blockbench. Use it to tell the human what the agent is doing or to ask them to look at the screen.

Render the current preview to a PNG on disk and return the path. This is how an agent looks at its own work. Set crop=true (default) to auto-crop to the model, or crop=false for the full viewport. The transparent viewport is composited over a solid background (override with "background", or disable with background:false). Returns a data URL too when include_data_url is true.

Render the model from several camera angles into one contact-sheet PNG and return its path. Use this to LOOK at your own work and catch proportion and texture problems before declaring a model finished. The agent can then read the image file.

Read a file from disk. encoding "auto" (default) returns text for text files and base64 for binary; force it with "text" or "base64". Reading uses Blockbench's own file layer and needs no plugin permission.

Write text or base64-decoded bytes to a file, creating parent directories is the caller's job. Uses Blockbench's file layer (no permission prompt).

List the entries of a directory. Needs the plugin file-system permission (the user is asked once; bb_request_fs can trigger the prompt explicitly). Supports recursion and a glob filter.

Recursively find files under a directory matching a glob such as "**/.json" or ".png". Needs file-system permission.

Stat a path: exists, type, size, modified time. Needs file-system permission.

Create a directory (recursively by default). Needs file-system permission.

Delete a file, or a directory when recursive is true. Needs file-system permission.

Ask the user for the plugin file-system permission (needed only by bb_list_dir, bb_glob, bb_file_info, bb_mkdir, bb_delete_path; reads and writes work without it). An optional scope limits the permission to one directory.

List outliner elements with their ids, transforms and (optionally) geometry. Filter by type or parent.

Create a cube element. Provide from+to, or from+size (Blockbench cubes use from/to where to is the exclusive upper bound). origin defaults to from. Optionally assign a texture to all faces, set per-face uv, and enable auto UV.

Create an empty group (bone) to hold elements or drive animation. Position it with origin.

Create a free-form mesh. vertices is a list of [x,y,z] (or a {key:[x,y,z]} map). faces is a list where each face is either [i0,i1,i2] indices into vertices, or {vertices:[i..], uv:[[u,v]..], texture}. UVs are stored per vertex.

Modify an existing mesh in place. With vertices+faces it redefines the geometry; with merge:true the new vertices/faces are appended. delete_faces / delete_vertices remove by key. Keys are shown by bb_list_elements {include_geometry:true}.

Create a locator, null_object, bounding_box, texture_mesh, armature or armature_bone. Pass its properties directly.

Change properties of one or more elements: name, origin, rotation, from/to/size (cubes), position (locators), inflate, visibility, export, locked, box_uv, autouv, shade, mirror_uv, uv_offset, color, and per-face overrides via faces:{north:{uv,texture,enabled,tint,rotation}}. Renaming more than one element at once is refused.

Move, rotate or scale elements. Use vector [x,y,z], or axis+amount. Move translates from/to/origin (cubes) or origin/position (others). Rotate adds degrees around the element origin. Scale multiplies size about the element origin (cubes, meshes, texture_mesh).

Copy elements (groups copy their children too). Optionally repeat and offset each copy.

Create repeated copies of elements along a grid — the correct way to build rows of windows, treads, spokes and so on instead of placing copies by hand. names may contain {i} and starts at 1.

Reflect elements across an axis-aligned plane (default x=0). copy=true duplicates first, which is the usual way to build a symmetrical half. Meshes keep correct winding.

Move elements under a new parent group (or "root").

Delete elements (groups delete their children).

Change the outliner selection. mode: replace (default), add, remove, toggle, none.

Create a new group around the given elements, positioned at their centre, and move the elements into it.

Assign a texture (by name/uuid) to cube or mesh faces, or clear it with null. For cubes, pass faces to limit which sides are changed.

Set UVs on one face. For cubes give uv=[x1,y1,x2,y2] in texture pixels. For meshes give uvs aligned to the face vertices, or a {vertex_key:[u,v]} map.

Set automatic UV mode on cubes: mode "faces" (autouv 1, per-face), "relative" (autouv 2), "box" (box_uv), or "off".

Run a static audit of the project and return a score plus findings: empty project, zero-size or degenerate cubes, meshes with too few vertices, untextured faces, UVs outside the texture, duplicate cubes, and out-of-bounds UVs. Fix and re-run before declaring a model finished.

List the project textures with size, UV resolution, layers and saved state.

Create a blank texture, optionally filled with a colour. Size defaults to the project texture resolution.

Paint a new texture from a preset and/or an ordered list of ops. Deterministic for a given seed. Presets: wood, planks, stone, cobble, metal, dirt, grass, leaves, bricks, fabric, skin, gem, noise, gradient. Ops: fill, noise, cells, gradient, radial, rect, circle, ellipse, line, checker, stripes, border, vignette, scatter, pixel, pixels, text, adjust, replace, blend. Example: {preset:"wood"} or {ops:[{op:"fill",color:"#2b3a55"},{op:"noise",color:"#101820",color2:"#8fb8de",scale:2,octaves:4},{op:"vignette",strength:0.5}]}.

Apply a list of ops onto an existing texture (adds to what is already there). Same ops as bb_generate_texture.

Set individual pixels on a texture — the precise way to hand-draw pixel art. pixels is a list of [x, y, color] with color "#rrggbb" or [r,g,b] or [r,g,b,a].

Read a rectangle of pixels from a texture. Use this to verify what was drawn: it returns rows of [r,g,b,a].

Load an image from disk or a data URL as a project texture.

Write texture PNGs to disk. Give a single target + path, or several targets + a directory.

Change texture metadata: name, folder, render_mode, pbr_channel, particle, fps, layers_enabled, saved.

Resize the texture image (nearest neighbour). uv_width/uv_height follow the new size unless keep_uv is true.

Remove textures from the project.

List the project animations with loop mode, length and per-bone keyframe counts.

Create a new animation. loop is "once", "loop" or "hold"; length is in seconds.

Change name, loop mode or length of an animation.

Remove an animation from the project.

Add a keyframe for a bone on rotation/position/scale. x/y/z are Molang expressions (default "0"), or plain numbers. The bone is referenced by group name or uuid.

Delete a keyframe by uuid, or the one nearest to a given time on a bone/channel.

Control the animation timeline: set the time, play, pause or stop.

List every Blockbench plugin that is present, with id, version, source, install state and whether it can be reloaded.

Install a Blockbench plugin from source code, a local file, or a URL. The code is written to the plugins folder, recorded so it loads on startup, and loaded immediately. Executes third-party code inside Blockbench.

Uninstall a Blockbench plugin by id and optionally delete its file.

Reload a dev/URL plugin without restarting Blockbench. Store plugins are not reloadable in place.

List user settings by id with their current values. Handy before bb_set_setting. filter matches the id.

Set a Blockbench user setting by id (e.g. viewport_zoom_speed, default_cube_size, shading).