BL
Developer Tools

Blockbench MCP Server AI Model & Texture Editor

Edit 3D models and pixel textures with AI in Blockbench using the MCP server plugin to connect AI agents to Blockbench's JavaScript API.

View on GitHub
Quick Install
npx -y @jasonjgardner/blockbench-mcp-plugin

Overview

The Blockbench MCP Server bridges AI agents and Blockbench’s JavaScript API so you can programmatically edit 3D models and pixel textures using natural language and agent workflows. It implements the Model Context Protocol (MCP) semantics for a local server that exposes Blockbench operations as callable tools. This lets generative agents (local or cloud) drive editing tasks—add geometry, modify UVs, paint pixels, or automate repetitive workflows—while keeping model state inside a running Blockbench instance.

This server is intended for developers who want to experiment with AI-driven model/texture editing, integrate AI assistants into Blockbench-based pipelines, or prototype agent orchestration that manipulates assets via Blockbench’s API. The plugin component communicates with Blockbench; the MCP server exposes a compatible API so agent frameworks can call high-level tools that map to Blockbench operations.

Features

  • Exposes Blockbench actions as MCP-compatible tools for AI agents
  • Connects to a running Blockbench instance via the Blockbench plugin
  • Supports model geometry edits (add/move/scale/rotate elements)
  • Supports pixel texture operations (paint, fill, replace, generate)
  • Authentication and basic configuration for local deployments
  • Logging and simple debugging endpoints for development

Installation / Configuration

Clone the repository, install dependencies, and start the server. The repo includes the Blockbench plugin that connects to the server; install that plugin inside Blockbench after starting the server.

  1. Clone and install
git clone https://github.com/jasonjgardner/blockbench-mcp-plugin.git
cd blockbench-mcp-plugin/server
npm install
  1. Create a minimal configuration file (.env or config.json) Example .env:
PORT=3366
API_KEY=changeme                  # required by the server for agent requests
BLOCKBENCH_PLUGIN_URL=http://localhost:3367  # plugin URL or ws used by Blockbench side
LOG_LEVEL=debug
  1. Start the server
npm start
# or, for development
npm run dev
  1. Install the Blockbench plugin
  • Open Blockbench
  • Install the plugin from the repo’s plugin directory (use Blockbench’s plugin installer or copy files into the Blockbench plugins folder)
  • In the plugin settings, set the MCP server URL to your running server (e.g. http://localhost:3366) and set the same API_KEY

Configuration notes:

  • The server expects the Blockbench plugin to initiate a persistent connection (HTTP/WebSocket) to receive commands or to route events back to agents.
  • API_KEY (or similar token) helps prevent unauthorized access on local networks; change the default before exposing the server.

Available Resources

The server exposes the following categories of resources to agents (actual tool names may vary; check the live /tools endpoint):

  • Model Tools

    • create_element: add new cube/box element
    • transform_element: translate/rotate/scale an element
    • delete_element: remove an element by id
    • list_elements: return current model element summaries

  • Texture Tools

    • paint_pixel: paint a pixel or region on a texture
    • fill_region: flood-fill an area on a texture
    • replace_color: replace color A with color B on the active texture
    • generate_texture_patch: ask an AI to produce a texture patch and apply it

  • Utility Tools

    • undo / redo
    • export_model: export to OBJ/GLTF/JSON
    • snapshot: capture current model/viewport and return an image for agent context

Tool invocation is designed to be synchronous or asynchronous depending on operation complexity. The server exposes metadata about each tool (name, description, parameters) via a discovery endpoint so agents can dynamically construct calls.

Example discovery request (HTTP):

GET /tools
Authorization: Bearer changeme

Use Cases

  • Texture refinement with an AI assistant

    • Prompt: “Make the hat pattern darker and add a white stripe on top.”
    • Flow: Agent calls generate_texture_patch to create the stripe, then apply_patch to merge it into the active texture. The server applies changes in Blockbench and returns a snapshot for verification.

  • Procedural model modification

    • Prompt: “Extend the character’s arms by 10% and rotate hands by 15 degrees.”
    • Flow: Agent calls list_elements to find arm element IDs, then calls transform_element to scale and rotate. After modifications, agent calls snapshot and verifies results.

  • Batch edits for asset pipelines

    • Scenario: Update 100 NPC models to use a new armor texture.
    • Flow: Agent orchestrator exports each model, applies the new texture with replace_color or apply_texture, and re-exports in the required format.

  • Creative iterations with visual feedback

    • Iteratively ask an AI to propose model adjustments and accept or reject them. Each suggestion is executed via a tool call, and the server returns snapshots so the agent (or human in the loop) can evaluate.

Tips for Developers

  • Use the discovery endpoint to inspect available tools and parameter schemas before generating calls from agents.
  • Keep the server local during development to avoid exposing your Blockbench session or models.
  • Log agent-to-server tool calls and responses to replay or audit automated edits.
  • If you need higher-level orchestrations, connect the MCP server to an agent framework (LangChain, custom orchestrator) that can use tool metadata for planning.

Repository and plugin: https://github.com/jasonjgardner/blockbench-mcp-plugin

For advanced customization (new tools, richer parameter validation), extend the server’s tools registry and update the Blockbench plugin to expose additional JS API methods.

Tags:developer-tools