Blockbench MCP

Codex-ready local MCP server for controlling Blockbench. This distribution combines the mature MCP implementation from jasonjgardner/blockbench-mcp-plugin with the local command-history idea from enfp-dev-studio/blockbench-mcp, then modernizes the result for direct use by Codex.

This is an independent community project. It is not affiliated with or endorsed by Blockbench, OpenAI, Jason J. Gardner, or ENFP Dev Studio.

What is inside

• A ready-to-load Blockbench desktop plugin with an embedded Streamable HTTP MCP server.
• 95 tools for projects, cubes, meshes, armatures, animation, UV editing, painting, textures, materials, cameras, import/export, and history.
• 11 resources, 7 resource templates, and 3 prompts.
• Codex-oriented server instructions and MCP tool annotations.
• Loopback-only networking, optional bearer authentication, a 16 MiB request limit, and a bounded privacy-aware audit log.
• A reproducible no-dependency build from the preserved upstream bundle.

See the full tool index, source comparison, and live verification report.

Requirements

• Blockbench desktop. The web app cannot host this local server.
• A local Codex client: ChatGPT desktop app, Codex CLI, or Codex IDE extension.
• Node.js 20 or newer only when rebuilding the plugin. It is not required to run the bundled plugin.

Installation

1. Clone or download this repository.

   git clone https://github.com/illia3/Blockbench-MCP.git
   cd Blockbench-MCP
   

2. Open Blockbench and select File > Plugins > Load Plugin from File. Choose plugin/blockbench_codex_mcp.js and allow local network access if Blockbench asks.

3. Keep these plugin defaults unless you need a different local setup:

   • port: 3000
   • MCP endpoint: /bb-mcp
   • prompt CDN: disabled
   • bearer token: empty (optional)

4. Connect Codex. In the ChatGPT desktop app or IDE extension, open Settings > MCP servers > Add server, choose Streamable HTTP, enter http://127.0.0.1:3000/bb-mcp, save, and restart the client.

   For file-based configuration, copy .codex/config.toml.example to either ~/.codex/config.toml or a trusted project's .codex/config.toml:

   [mcp_servers.blockbench]
   url = "http://127.0.0.1:3000/bb-mcp"
   startup_timeout_sec = 10
   tool_timeout_sec = 120
   enabled = true
   required = false
   default_tools_approval_mode = "writes"
   

5. Keep Blockbench open. Check http://127.0.0.1:3000/bb-mcp/ready, then use /mcp in Codex to confirm that blockbench is connected.

Codex MCP configuration details are documented in the official OpenAI MCP guide.

What to expect

The MCP server runs inside Blockbench, so commands act on the currently open desktop session. Read-only inspection can run automatically. The supplied Codex configuration asks for approval before tools that are not marked read-only. Blockbench undo/redo remains available for supported operations.

Some tools require a compatible project format, an active texture, a selected element, or an open project. Optional Hytale capabilities appear only when the corresponding Blockbench environment is available.

Suggested first prompts

• Inspect the open Blockbench project and summarize its hierarchy.
• Create a 16 x 16 x 16 cube named body and place it at the origin.
• List the textures and materials used by the selected elements.
• Capture a preview screenshot and identify visible modeling issues.
• Show the last 20 Blockbench MCP audit entries.

Security

The server binds explicitly to 127.0.0.1; do not expose it through port forwarding, a reverse proxy, or a firewall rule. Bearer authentication is optional and disabled by default so this repository never stores a secret. See SECURITY.md for safe token setup and the audit policy.

The risky_eval and UI-emulation tools are powerful. Keep the Codex approval mode set to writes or stricter and review their arguments before approval.

Troubleshooting

• Codex cannot connect: keep Blockbench open, verify the plugin is loaded, and open the /ready URL.
• The server is missing from /mcp: save the MCP entry and restart the desktop app or IDE extension.
• A tool reports that no project is open: create or open a Blockbench project, then retry.
• Unauthorized response: the token configured in Blockbench must match the Authorization environment header configured for Codex.
• Port already in use: stop the conflicting service or change the plugin port and the Codex URL together.

Development and verification

Rebuild and check the committed plugin:

npm run build
npm run check
npm test

source/build-custom.mjs deterministically applies the documented changes to the preserved upstream 1.6.1 bundle. npm test also fails if the generated plugin differs from the committed artifact.

Attribution and license

The included plugin is a modified work of Jason J. Gardner's blockbench-mcp-plugin 1.6.1 and is distributed under GPL-3.0-only. The ENFP Dev Studio repository was analyzed, but its source code was not copied. See THIRD_PARTY_NOTICES.md, MODIFICATIONS.md, and LICENSE.