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

> **Download:** get **`mcp-for-mblock-windows-x64.zip`** from
> [Releases](https://github.com/blame-me/mblock-mcp/releases/latest) — 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. ✅

## 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.