# blockbench-mcp-plugin, an MCP server for Blockbench, and the two ways it reaches your editor

> blockbench-mcp-plugin exposes Blockbench to an AI agent through two servers: an HTTP endpoint hosted by the desktop app, and a headless stdio server that edits .bbmodel files on disk with no GUI running. The headless path is the more useful of the two, and the gap between tagged releases and unversioned install commands is the thing to watch.

**jasonjgardner/blockbench-mcp-plugin** — Adds MCP server to Blockbench

- Repository: https://github.com/jasonjgardner/blockbench-mcp-plugin
- Website: https://jasonjgardner.github.io/blockbench-mcp-plugin/
- Stars: 568 · Forks: 59
- Language: TypeScript
- License: GPL-3.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/jasonjgardner-blockbench-mcp-plugin

## Two servers behind one plugin: the desktop HTTP bridge and the headless stdio server

blockbench-mcp-plugin is an MCP server for Blockbench, the low poly modeller, and the interesting part of the design is that it ships two different servers with different transports.

The desktop plugin path is HTTP. You install a single JavaScript file into the Blockbench desktop app through File, then Plugins, then Load Plugin from URL, pasting the mcp.js URL hosted on the project's GitHub Pages site. Blockbench then hosts an MCP endpoint, and the port and endpoint path are configured under Settings, then General, with MCP Server Port and MCP Server Endpoint. The documentation's examples use the default values, which are port 3000 and the path bb-mcp, so the endpoint is http://localhost:3000/bb-mcp.

The headless path is stdio. A separate server edits, validates, converts and renders .bbmodel files directly, with no Blockbench running at all. The documentation stresses the operational difference: each agent can start its own process, so several agents can work in parallel while you keep using the editor. It is run straight from GitHub with:

```bash
```bash
npx -y github:jasonjgardner/blockbench-mcp-plugin --root ./models
```
```

The --root argument is required and limits file access to that directory, which is the sandbox boundary of the whole thing. The headless README covers client configuration, the tool list and the limits.

So the two are not redundant. The desktop server drives the live editor, with the model open in front of you. The headless server works on files on disk, with no GUI involved. The documentation says you can use either server or both, and gives configuration examples for both in every client it documents.

## Registering the servers with an MCP client

The client configuration is the bulk of the documentation, and it is long because MCP clients all spell the same registration differently.

The generic path uses a tool called mcp-add, and it covers both servers in one snippet:

```bash
```bash
# Desktop plugin (HTTP)
npx mcp-add --type http --url "http://localhost:3000/bb-mcp" --scope project

# Headless (stdio)
npx mcp-add --name bbmodel --type stdio --command "npx -y github:jasonjgardner/blockbench-mcp-plugin --root /path/to/models" --scope project
```
```

Note the difference in shape. The desktop plugin is registered as an HTTP server pointing at a URL, while the headless server is registered as a stdio server with a command string, which is the whole npx invocation including the --root path.

For Claude Code the same two registrations are expressed as subcommands:

```bash
```bash
claude mcp add blockbench --transport http http://localhost:3000/bb-mcp

# Headless (stdio)
claude mcp add bbmodel --transport stdio -- npx -y github:jasonjgardner/blockbench-mcp-plugin --root /path/to/models
```
```

For Codex there is a plugin marketplace route as well as direct registration:

```bash
```bash
# Desktop plugin (HTTP)
codex mcp add blockbench --url http://localhost:3000/bb-mcp

# Headless (stdio)
codex mcp add bbmodel -- npx -y github:jasonjgardner/blockbench-mcp-plugin --root /path/to/models
```
```

The headless registration there uses the -- separator to hand the server command to the client.

The JSON config files for other clients are variations on the same two shapes. VS Code uses a servers object with a url and type of http for the desktop server, and a stdio entry with a command and args array for the headless one. It also declares an input, a promptString named rootDir that the ${input:rootDir} placeholder in the args refers to, defaulting to ${workspaceFolder}/models. That is a nicer arrangement than hard coding a path, because the model directory follows the workspace.

For OpenCode the interactive command is:

```bash
```bash
opencode mcp add
```
```

and the same two servers can be written into opencode.json as a remote entry with a url and a local entry with a command array:

```json
```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "blockbench": {
      "type": "remote",
      "url": "http://localhost:3000/bb-mcp",
      "enabled": true
    },
    "bbmodel": {
      "type": "local",
      "command": ["npx", "-y", "github:jasonjgardner/blockbench-mcp-plugin", "--root", "/path/to/models"],
      "enabled": true
    }
  }
}
```
```

One practical note in the documentation deserves repeating, because it is the kind of detail that costs an afternoon on Windows. Clients that cannot launch npx directly should use command cmd and prepend /c and npx to args, and the Claude Desktop examples are shown for both macOS and Linux and for Windows separately to make that difference visible.

## Loading the plugin from a URL into the desktop app

The desktop plugin installation is deliberately not a build step. The instruction is to open the desktop version of Blockbench, go to File and then Plugins, click Load Plugin from URL, and paste the URL of the hosted mcp.js file, which lives under the project's GitHub Pages site.

The consequence is that the desktop path is a fetch from a web host at the moment you install it, and Blockbench is running code that came over the network. There is no version number in that URL and no checksum in the instructions, so the file you get is whatever is published at that address when you click the button. The release list in the repository, v1.9.3 on 2026-09-27, v1.10.0 on 2026-10-01 and v1.10.1 on 2026-10-16, tells you what has been published, but the installation procedure itself does not tie a specific tag to the file you fetch.

The MCP server port and endpoint settings are what turn the plugin into a server. Once Blockbench is running with the plugin loaded and the port configured, the endpoint is reachable over HTTP on localhost, and that URL is what you register in a client.

The distinction between this and the headless server matters for anyone evaluating the project on a shared machine. The desktop server only exists while Blockbench is open, and it only exposes what the loaded plugin exposes. The headless server exists only while the agent's process is running, and it can only touch files under the --root directory. Neither is a background service that survives a reboot, and neither listens on anything other than the local machine unless you point a client at it.

## What the plugin repository actually contains

The top level entries describe a project that is bigger than a single plugin file, and the directory names are the quickest way to understand the scope.

There is a server/ directory and a lib/ directory, plus a headless/ directory that holds the stdio server. The ui/ directory is the interface, prompts/ holds the prompt definitions, and macros/ holds what are presumably reusable command sequences. Then there is a build/ directory with the build and release scripts, a benchmarks/ directory, a tests/ directory, a docs/ directory and a releases/ directory. The entry points are index.ts and types.d.ts, and the build output that clients actually load is dist/mcp.js, which the package manifest lists as main.

The toolchain is Bun, not Node. The manifest scripts are all bun invocations: the test script is bun test, the headless test is bun test headless, and there are separate live smoke test scripts for identity, inspection, action wrappers, PBR, and animation, plus a live smoke runner for the headless side. The build script runs a prompt manifest generation step before bundling, and the dev script runs the same generation step with a sourcemap build.

The presence of a benchmarks/ directory with its own plan, run, test, typecheck and report scripts is the most unusual thing in the manifest, and it is worth a reader's attention. The documentation does not describe what is being measured or what the results mean, so the honest statement is that the project has a benchmark harness rather than any particular claim about speed.

There are also agent-facing files, AGENTS.md and CLAUDE.md, a .agents/ directory, a .coderabbit.yaml, an llms.txt and an llms-install.md, and a prompts manifest generated by build/generate-manifest.ts. The licence is GPL-3.0-only.

## Where this plugin is the wrong tool

The first wrong case is a workflow that needs to stay inside Blockbench's own editing model. The desktop server is bound to a running Blockbench instance, so anything that requires the app to be open, focused and in a particular mode is constrained by that. The headless server works on .bbmodel files, which is a narrower surface than the full editor.

The second wrong case is a machine where running a local HTTP server on a fixed port is not acceptable. The desktop server listens on port 3000 by default and the examples hard code that URL in every client config. If port 3000 is taken, or if a policy forbids an unauthenticated local HTTP endpoint, the desktop path becomes awkward. There is no authentication described for that endpoint anywhere in the documentation.

The third wrong case is a team that requires reproducible, pinned installs. The desktop plugin is loaded from a URL, and the headless server is run with npx -y straight from GitHub, which resolves the default branch at the moment it runs. Neither path pins a version. The release tags exist, but neither of the two documented install commands references one.

The fourth wrong case is a user who wants to script Blockbench without an agent. The whole surface is MCP tools. If you want a Python script that edits a model file, this repository does not describe a library API for that, and the headless server's tool list is documented in its own README rather than here.

The fifth wrong case is expecting a rendered output pipeline. The headless server is described as rendering .bbmodel files, but the demo reel in the documentation was rendered in Blender, and the repository is not a renderer with an export pipeline for shipping assets.

## This plugin against scripting the format directly

The alternative is to skip MCP and work with .bbmodel files as data, using whatever scripting language you already use.

The difference in approach is about where the domain knowledge sits. A .bbmodel file is JSON, and a direct approach is to read it, edit the JSON, and write it back, with your own code that knows which fields to change for a new element, a texture, or an animation. That approach is fast, scriptable, version controllable and has no server to run. What you give up is everything the plugin knows about the format, including validation, conversion and rendering, and any check that a hand-edited file still opens correctly in Blockbench.

The plugin's approach puts that knowledge in a set of MCP tools, so the agent asks for an operation rather than constructing JSON. That buys you a validation path, since the server is described as editing, validating, converting and rendering, and it buys you the ability to drive the live editor, which a file-level script cannot do.

The cost is a runtime dependency on an agent loop and a Node or Bun process, plus the MCP handshake, plus the plugin file loaded from a web host for the desktop path. A CI job that needs to tweak one field in one model file does not want any of that.

There is also a middle option that the two servers themselves illustrate. The headless server is essentially the file-level capability packaged as an agent tool, with a --root sandbox instead of a GUI. A team that wants the validation and conversion logic without the agent will find the tool list is the specification of what is actually available, and that specification lives in headless/README.md rather than in the main documentation.

## Maintenance, versioning and what the release cadence tells you

The project ships regular tagged releases. The recent list shows v1.9.3 on 2026-09-27, v1.10.0 on 2026-10-01 and v1.10.1 on 2026-10-16, and the last push was on 2026-10-16, the same day as the latest tag. The package version in the manifest is 1.10.1, and the licence is GPL-3.0-only.

That cadence matters for the way the plugin is consumed, because of how it is consumed. The desktop path fetches a file from a URL, and the headless path runs npx -y against the GitHub repository, which resolves whatever is on the default branch at that moment. Neither is a versioned dependency in the ordinary sense. A tag exists, but pointing at it requires editing the URL or the npx spec yourself, and the documentation does not walk through that.

The GPL-3.0-only licence is worth understanding before you deploy this in a commercial setting. It is a copyleft licence, so a modified version distributed to others carries the same obligation. It is a fine licence for a plugin that runs on the user's own machine and is loaded from its author's server, and it is a licence to think about if you fork the plugin, bundle it into a product, or run the headless server as part of a service you distribute. That is a question for whoever handles licensing in your organisation, not a conclusion to draw from a badge.

The repository also carries a substantial agent-facing documentation layer, with AGENTS.md, CLAUDE.md, llms.txt and llms-install.md alongside the human README, which suggests the project treats the agent as a first class consumer of the documentation rather than an afterthought.

## Conclusion

blockbench-mcp-plugin suits a modeller who wants an agent to edit models as files in parallel with their own work, or who wants to drive the live editor over a local endpoint, and who is comfortable with a plugin fetched from a web host. It does not suit a pipeline that needs reproducible pinned installs, since neither the URL install nor the npx invocation references a release tag, or a machine that cannot run a local unauthenticated HTTP server on port 3000. Before you adopt it, read headless/README.md for the tool list and the limits, decide which of the two servers your client will use since the documentation configures both, and pin a version yourself in the npx spec or the plugin URL if your environment needs a fixed build.

## FAQ

### How do I install the Blockbench MCP plugin?

Open the desktop version of Blockbench, go to File and then Plugins, click Load Plugin from URL, and paste the URL of the hosted mcp.js file from the project's GitHub Pages site. The MCP server port and endpoint are then configured under Settings, then General, with the documented examples using port 3000 and the path bb-mcp.

### What is the difference between the headless server and the desktop plugin?

The headless stdio server edits, validates, converts and renders .bbmodel files directly without Blockbench running, and each agent can start its own process so several can work in parallel. The desktop plugin is an HTTP server hosted by a running Blockbench instance on the default http://localhost:3000/bb-mcp endpoint, and it needs the plugin installed in the app.

### How do I run the headless Blockbench MCP server?

Run npx -y github:jasonjgardner/blockbench-mcp-plugin --root ./models. The --root argument is required and limits file access to that directory. On Windows, clients that cannot launch npx directly should use cmd as the command and prepend /c and npx to the args.

### Which clients does the blockbench-mcp-plugin document?

The documentation covers VS Code, Claude Desktop for macOS, Linux and Windows, Claude Code, Codex, Antigravity, Cline, Ollama and OpenCode, with both a JSON configuration file and, for several of them, command line registration steps.

### What licence is the blockbench-mcp-plugin released under?

The package manifest declares the licence as GPL-3.0-only, and the repository has a LICENSE file at the top level. The current package version is 1.10.1, released on 2026-10-16.

## Sources

- [jasonjgardner/blockbench-mcp-plugin on GitHub](https://github.com/jasonjgardner/blockbench-mcp-plugin)
- [License: GPL-3.0](https://github.com/jasonjgardner/blockbench-mcp-plugin/blob/main/LICENSE)
- [Project website](https://jasonjgardner.github.io/blockbench-mcp-plugin/)
- [README](https://github.com/jasonjgardner/blockbench-mcp-plugin/blob/main/README.md)
- [Releases](https://github.com/jasonjgardner/blockbench-mcp-plugin/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jasonjgardner-blockbench-mcp-plugin