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: scratch-mcp

Everyday use (just talk to your AI)

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.