Content
# microbit-claude-mcp
[](https://www.npmjs.com/package/microbit-claude-mcp)
[](https://github.com/eoinjordan/microbit-mcp/actions/workflows/publish.yml)
MCP server for micro:bit v2 CODAL projects. It exposes a small REST API plus an MCP stdio bridge so agents can read and write `source/main.cpp`, list sources, validate a project, and run `build.py` to generate `MICROBIT.hex`.
## Features
- Validate a CODAL project layout
- Read and write source files (defaults to `source/main.cpp`)
- List C/C++ source files
- Run `build.py` to build firmware
- REST + MCP stdio transport
## Requirements
- A micro:bit v2 CODAL project (for example `microbit-v2`) with `build.py` and `source/`
- Python 3 available as `python` (or set `MICROBIT_PYTHON`)
- The micro:bit toolchain required by your CODAL project
- Node.js 18+
## Installation
Global install:
```sh
npm install -g microbit-claude-mcp
```
Local dev:
```sh
npm install
npm run build
npm run build:mcp
```
## Usage
### Run the REST server
```sh
microbit-claude-mcp
```
Defaults to port `3040`. Override with:
```sh
$env:PORT=3041
microbit-claude-mcp
```
### Run the MCP stdio server
```sh
node build/mcp.js
```
If your REST server is not on the default port, set one of:
- `MICROBIT_API_URL` (full URL, for example `http://localhost:3041`)
- `MICROBIT_API_PORT` (port only, for example `3041`)
### MCP client config
```json
{
"mcpServers": {
"microbit-mcp": {
"command": "node",
"args": ["/absolute/path/to/build/mcp.js"]
}
}
}
```
## Tutorial (10 minutes)
1) Start the REST server.
2) Validate the project:
- `POST /validate`
- Body: `{ "projectRoot": "/path/to/microbit-v2" }`
3) Read the main source:
- `POST /read_source`
- Body: `{ "projectRoot": "/path/to/microbit-v2" }`
4) Write a small change:
- `POST /write_source`
- Body: `{ "projectRoot": "/path/to/microbit-v2", "content": "// your code" }`
5) Build (optional):
- `POST /build`
- Body: `{ "projectRoot": "/path/to/microbit-v2" }`
## Environment variables
- `PORT`: REST server port (default `3040`)
- `MICROBIT_API_URL`: REST base URL for the MCP bridge
- `MICROBIT_API_PORT`: REST port for the MCP bridge
- `MICROBIT_PYTHON`: Python executable for `build.py`
- `MICROBIT_BUILD_TIMEOUT_MS`: Build timeout in ms (default `120000`)
## REST API
### Health
- `GET /health` -> `{ status: "ok" }`
### Validate
- `POST /validate` body: `{ projectRoot: string }`
- Returns `{ valid, missing, projectRoot }`
### List sources
- `POST /list_sources` body: `{ projectRoot: string }`
- Returns `{ files: string[] }`
### Read source
- `POST /read_source` body: `{ projectRoot: string, relativePath?: string }`
- Returns `{ path, content }`
### Write source
- `POST /write_source` body: `{ projectRoot: string, relativePath?: string, content: string }`
- Returns `{ success, path, bytes }`
### Append source
- `POST /append_source` body: `{ projectRoot: string, relativePath?: string, content: string }`
- Returns `{ success, path, bytes }`
### Build
- `POST /build` body: `{ projectRoot: string, timeoutMs?: number }`
- Returns `{ success, exitCode, stdout, stderr, hexPath, hexExists }`
## Clawdbot / Moltbot compatibility
This repo ships a skill at `skills/microbit-mcp/SKILL.md`.
Enable it in Moltbot:
```json
{
"skills": {
"load": {
"extraDirs": ["~/.clawdbot/skills"],
"watch": true,
"watchDebounceMs": 250
},
"entries": {
"microbit-mcp": {
"enabled": true,
"env": {}
}
}
}
}
```
## Example prompts
- "Open this micro:bit project and add a scrolling LED message that says HELLO."
- "Read source/main.cpp and explain what the program currently does."
- "Add a button A handler that toggles the LED matrix, then build the firmware."
## Testing
```sh
npm test
```
The tests focus on REST behavior. The build endpoint is not exercised unless a working CODAL toolchain is installed.
## Publishing
1. Update `package.json` version
2. Build:
```sh
npm run build
npm run build:mcp
```
3. Publish:
```sh
npm publish --access public
```
4. Tag and push to trigger `.github/workflows/publish.yml`
## Project structure
- `src/index.ts` REST API
- `src/mcp.ts` MCP stdio bridge
- `skills/microbit-mcp/SKILL.md` agent skill
- `server.json` MCP registry metadata
## Contributing
PRs welcome. Please keep changes small and include tests where possible.
## License
MIT
