Blocksworld Simulation

You can connect an MCP-enabled client to the Blocksworld Simulation through a dedicated MCP server. This bridge lets you control the simulation with LLMs, perform planning, verify multi-step plans, and inspect the current state in real time. It supports actions like picking up, stacking, and placing blocks, while exposing rules and state information to your AI workflows.

How to use

You interact with the Blocksworld MCP server by running it locally and then connecting your MCP client to it. The server presents seven tools that let you manipulate the simulation, inspect the world state, and verify plans without executing them. Use your MCP client to call each tool in sequence to form your desired plan, verify the plan’s correctness, and then execute actions step by step.

How to install

Prerequisites and environment setup ensure you can run the MCP server and connect to the local simulation.

# Clone the MCP server repository
git clone https://github.com/hsu-aut/llmstudy_mcp-server.git
cd llmstudy_mcp-server

# Install dependencies
poetry install

# Run the MCP server (this starts the server and keeps it running in the foreground)
poetry run blocksworld-mcp-server

Configuration and notes

The MCP server by default connects to the Blocksworld Simulation REST API at http://localhost:5001. If you need to point the server at a different API URL, modify the configuration where the simulation API URL is defined in the code.

Example local development configuration for the MCP server CLI is shown here as a ready-to-run stdio setup. Use this to start the server from your environment.

{
  "mcpServers": {
    "blocksworld": {
      "type": "stdio",
      "command": "poetry",
      "args": [
        "--directory",
        "/path/to/llmstudy_mcp-server",
        "run",
        "blocksworld-mcp-server"
      ]
    }
  }
}

Tips for practical use

• Use status() to get a full picture of the current block positions, stack configurations, and robot state before planning.
• Retrieve rules() to understand preconditions and allowed actions, which helps your planning components reason about feasibility.
• Verify your plan with verify_plan() before executing actions to catch errors early and improve planning accuracy.
• Execute actions one by one to maintain clear reasoning steps in your agent’s execution trace.

Notes on testing and debugging

Plan verification is recommended to happen before any action is executed. The environment provides a guard against executing complex multi-step plans wholesale by default, encouraging step-by-step reasoning.

Available tools

pick_up

Pick up a block from the ground with the robot, given the block name. Preconditions: the block is on the ground, is clear, and the robot is idle.

unstack

Remove a block from the top of another block. Preconditions: block_x is directly on top of block_y, block_x is clear, and the robot is idle.

put_down

Place the held block on the ground. Preconditions: the robot is holding the specified block and there is a free ground position.

stack

Place the held block on top of another block. Preconditions: the robot is holding block_x and block_y is clear.

status

Return the current state of the simulation, including all block positions, stack configurations, and robot state in a complete JSON object.

rules

Provide the complete description of blocksworld rules and constraints in Markdown format, including environment constraints, preconditions, and available actions.

verify_plan

Verify a multi-step plan without executing it. Returns success or a detailed error message indicating where the plan fails.