Skip to main content
Glama
Sign In
mBlock MCP

mBlock MCP

by blame-me
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mBlock MCP — let AI build with blocks, in your mBlock app

Download: get mcp-for-mblock-windows-x64.zip from Releases — unzip it and you get mcp-for-mblock.exe + README.md. That's the whole thing. No Node.js, no installs, no setup screens.

It lets AI apps (Claude Desktop, Cursor, VS Code, Windsurf, Cline, OpenCode, Claude Code, Gemini CLI) build and edit mBlock 5 block projects — sprites, mBot, CyberPi/mBot2, Arduino Uno — and put blocks straight into your open mBlock app.

Setup (3 minutes, do once)

Step 1 — Plug it into your AI app. Double-click mcp-for-mblock.exe. A window opens, sets everything up by itself (it backs up your existing settings first — nothing of yours is lost), and tells you what it did. Close the window.

Don't trust double-click? Same thing from a terminal:

mcp-for-mblock.exe --setup

Step 2 — Restart your AI app. This is the step everyone misses: every app (Claude Desktop, Cursor, Windsurf, OpenCode, VS Code…) only reads its MCP setup when it launches. Fully quit it first — Claude Desktop hides in the system tray, so right-click → Quit — then open it again. Then ask it:

list my mBlock projects

A Welcome.mblock sample is already there. If it lists it, you're connected. ✅

Step 3 — Connect the mBlock app (optional, for live blocks). You need this only if you want the AI to put blocks into your open mBlock window. Without it, the AI still builds full .mblock files you open yourself.

  1. Get the bridge file — either ask your AI "give me the mBlock bridge file", or run:

    mcp-for-mblock.exe --get-bridge

  2. Open the mBlock 5 app on your computer.

  3. Drag the file mblock-bridge.mext into the mBlock window. Done.

  4. Ask your AI "is the mBlock app connected?" — it should say yes. ✅

Related MCP server: DC-COCO-MCP

Everyday use (just talk to your AI)

Say this

What happens

Make a sprite chase game

AI builds the full project file

Add a repeat-4-turn-15 stack to Sprite1

AI adds the blocks

Check my project for mistakes

AI validates every block link

Put it in my open mBlock app and run it

AI injects + runs live (needs Step 3)

My mBot should follow a line

AI builds the robot script

Something's broken, what do I do?

AI runs a health check and tells you

Your files live in Documents\mblock-projects. Open any .mblock in the mBlock app normally.

If something doesn't work

  1. AI doesn't show any mBlock tools → you skipped restarting it in Step 1. Restart, then ask list my mBlock projects.

  2. "Bridge offline" → the mBlock app isn't linked. Redo Step 3 (the .mext drag takes 5 seconds).

  3. "Project not found" → tell the AI the exact file name, or ask it to list projects first.

  4. Blocks look wrong → ask the AI to validate the project — it finds bad links and typos itself.

  5. Still stuck → ask the AI to run doctor and explain the result. Paste that output if you ask a human for help.

To remove everything: delete the exe, remove the mblock entry from your AI app's config (a .bak backup of the original sits next to it), and optionally delete Documents\mblock-projects.

Good to know

  • Everything runs on your own computer. Your projects never leave your machine (except to the AI app you already use).

  • No internet needed, except the AI app itself.

  • Works on Windows. macOS/Linux run the same server from source — see below.

For developers

Source is TypeScript + MCP SDK v2 (src/). Build & test:

npm install
npm run build
npm test
node scripts/smoke.mjs

Rebuild the exe: powershell -ExecutionPolicy Bypass -File scripts/build.ps1. The exe is a Node SEA bundle; the mBlock-app bridge files are embedded in it (src/bridge-assets.ts) and exported via --get-bridge. Full tool docs, mcp.example.json, and CI live in this repo.

Available Tools

36 tools
add_blockA
Idempotent

Add a single block, optionally chained after afterId. Tip: describe_opcode first.

Inputs: opcode (required), x, y, path, +6 more.

add_scriptB
Idempotent

Put a whole stack of blocks at once (file). First entry should be a hat. Handles next/parent/shadows + SUBSTACK.

Inputs: blocks (required), x, y, path, +3 more.

add_spriteC

Add a new sprite target.

Inputs: name, path, confirm.

add_variableC

Add a global variable to a target.

Inputs: name (required), path, value, target, +1 more.

app_get_codeA
Read-onlyIdempotent

LIVE: get transpiled Python/ArduinoC via device.getCode() in the app (like preprocess).

Inputs: no named parameters.

app_get_varA
Read-onlyIdempotent

LIVE: read a global variable from the app workspace.

Inputs: name (required).

app_put_and_runA
Idempotent

LIVE combo (like upload-and-monitor): inject a script, run its hat, then read back a variable — new blocks to visible result in one call.

Inputs: blocks (required), x, y, target, +2 more.

app_put_scriptA
Idempotent

LIVE: put a script into the OPEN mBlock app via the bridge. Falls back to file hint if offline.

Inputs: blocks (required), x, y, target.

app_run_hatB
Idempotent

LIVE: run a hat block in the app (app.workspace.runBlocks).

Inputs: opcode (required).

app_sensor_snapshotB
Read-onlyIdempotent

LIVE: non-blocking sensor/variable read (like monitor-snapshot). Pushes a state request and returns the latest bridge push + live var read.

Inputs: name, timeoutMs.

app_set_varC
Idempotent

LIVE: set a global variable in the app workspace.

Inputs: name (required), value (required).

app_statusA
Read-onlyIdempotent

Check if the mBlock 5 app bridge is connected (open app + drag in mblock-bridge.mext).

Inputs: no named parameters.

bridge-filesA
Idempotent

Write the mBlock-app bridge files (.mext + setup JS) to a folder so you can drag the .mext into the app. Run once.

Inputs: folder.

delete_blockA
DestructiveIdempotent

Delete a block (+ its next-chain by default). Requires confirm:true.

Inputs: blockId (required), path, target, confirm, +1 more.

describe_opcodeA
Read-onlyIdempotent

Inputs/fields/example for one opcode. Run before add_block to get params right.

Inputs: opcode (required).

doctorA
Read-onlyIdempotent

Health check for the whole mBlock setup: server, bridge app link, projects folder, bridge file. Run first when anything behaves oddly.

Inputs: no named parameters.

export_codeB
Read-onlyIdempotent

Export a human-readable listing of every script in the project (like export-binary/preprocess: review before running).

Inputs: path, target.

get_blockB
Read-onlyIdempotent

Full JSON of one block + its catalog definition.

Inputs: blockId (required), path, target.

get_scriptB
Read-onlyIdempotent

Follow the next-chain from a hat block and return the ordered script.

Inputs: hatId (required), path, target.

import_mext_catalogA
Idempotent

Import a community .mext block catalog JSON so its opcodes become known (no more unknown warnings).

Inputs: path (required).

list_blocksB
Read-onlyIdempotent

List blocks on a target (paginated).

Inputs: path, limit, offset, target, +1 more.

list_costumesC
Read-onlyIdempotent

List costumes/backdrops of a target (like lib-examples: starter art inventory).

Inputs: path, target.

list_devicesA
Read-onlyIdempotent

Supported device profiles (sprite, mbot, cyberpi, arduino_uno, stage).

Inputs: no named parameters.

list_opcodesA
Read-onlyIdempotent

Searchable block catalog (core + imported .mext). Filter by device and query.

Inputs: query, device.

list_soundsC
Read-onlyIdempotent

List sounds of a target.

Inputs: path, target.

list_targetsB
Read-onlyIdempotent

List Stage/sprites/devices in a project.

Inputs: path.

move_blockC
Idempotent

Move a top-level block to x/y.

Inputs: x (required), y (required), blockId (required), path, +2 more.

project-archiveA
Idempotent

Zip a project (.mblock + .bak + profile) for sharing or backup.

Inputs: path (required), output.

project-attachA
Idempotent

Save default project/target (project.yaml) so later block tools can omit path/target. Run once per project.

Inputs: path (required), target.

project-duplicateA
Idempotent

Duplicate a project to a new path (safe way to try edits).

Inputs: dest (required), path (required).

project-listA
Read-onlyIdempotent

List .mblock/.sb3 projects under a folder. Start here to find a project file.

Inputs: root.

project-newA

Create a new .mblock from a template (blank, sprite_chase, mbot_forward, arduino_blink).

Inputs: path (required), template.

project-openC
Read-onlyIdempotent

Open a .mblock/.sb3 and summarize targets, extensions, block counts.

Inputs: path (required).

project-validateA
Read-onlyIdempotent

Validate block links (parent/next), unknown opcodes, missing x/y. Run before sharing or injecting.

Inputs: path (required).

rename_targetA
Idempotent

Rename a sprite/device target (updates monitors' spriteName too).

Inputs: name (required), target (required), path, confirm.

set_block_fieldC
Idempotent

Set an input param or dropdown field on a block.

Inputs: kind (required), name (required), value (required), blockId (required), +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    B3/5.0

    Scored across 36 tools

    Disambiguation5/5

    Each tool targets a distinct operation—project management, block manipulation, live app control, or asset listing. Overlaps like add_script vs add_block vs app_put_script are clearly differentiated by context (file-based vs live bridge). No two tools serve the same purpose.

    Naming Consistency2/5

    Naming is inconsistent: some tools use hyphens (project-validate, project-list, bridge-files) while others use underscores (list_targets, get_block, add_script). Verb styles also vary (list, get, add, set, delete, move, rename, export, import, run, put). Not a predictable pattern.

    Tool Count2/5

    With 36 tools, the server is over-scoped for an MCP surface. Even though it covers a broad domain, the count exceeds the 25+ threshold for 'too many'. Many tools are narrow (e.g., app_sensor_snapshot, list_costumes), contributing to bloat.

    Completeness4/5

    The server covers project lifecycle (new, open, duplicate, archive, validate), block/script editing (add, delete, move, set, get), and live app integration (put, run, read vars, get code). Minor gaps exist—no project deletion or block field retrieval—but core workflows are well-supported.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers