Blocksworld Simulation MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
π€ Blocksworld Simulation MCP Server
A Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to interact with the Blocksworld Simulation through tool calls. This allows AI agents or LLMs in general like Claude, ChatGPT, and other MCP-compatible systems to solve planning problems by directly controlling the simulation.
π― What is This?
This MCP server exposes the Blocksworld Simulation's REST API as a set of tools that LLMs can use. Instead of just talking about block manipulation, LLMs can actually:
Execute actions: Pick up, put down, stack, and unstack blocks
Query state: Get real-time information about block positions and robot status
Verify plans: Test multi-step plans before execution
Learn rules: Retrieve the complete set of constraints and preconditions
Perfect for:
π¬ AI Planning Research: Test LLM reasoning and planning capabilities
π Educational Projects: Demonstrate AI problem-solving in action
π§ͺ Agent Development: Build and test autonomous AI agents
π Benchmarking: Evaluate LLM performance on classic planning problems
Related MCP server: rest-to-mcp
β¨ Features
7 MCP Tools: Complete set of blocksworld operations exposed as LLM tools
Rich Descriptions: Each tool includes detailed preconditions and effects
Plan Verifciation: LLMs can verify plans without executing them
State Inspection: Query current simulation state at any time
Rule Discovery: LLMs can learn the rules dynamically
Type Safety: Pydantic models ensure correct tool usage
π Quick Start
Prerequisites
Python 3.10+ installed
Blocksworld Simulation running on
localhost:5001Follow the simulation setup guide
Make sure the simulation is started before using the MCP server
Installation
# Clone the repository
git clone https://github.com/hsu-aut/llmstudy_mcp-server.git
cd llmstudy_mcp-server
# Install dependencies
poetry install
# Run the MCP server
poetry run blocksworld-mcp-serverUsing with Claude Desktop
Add this to your Claude Desktop configuration file:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"blocksworld": {
"command": "poetry",
"args": [
"--directory",
"/path/to/llmstudy_mcp-server",
"run",
"blocksworld-mcp-server"
]
}
}
}Restart Claude Desktop, and the blocksworld tools will be available!
π οΈ Available Tools
The MCP server provides the following tools to LLMs:
1. pick_up
Pick up a block from the ground.
Parameters:
block(str): The name of the block to pick up
Preconditions:
Block must be on the ground (not stacked)
Block must be clear (nothing on top)
Robot must be idle (not holding anything)
2. unstack
Remove a block from the top of another block.
Parameters:
block_x(str): The block to removeblock_y(str): The block underneath
Preconditions:
Block x must be directly on top of block y
Block x must be clear
Robot must be idle
3. put_down
Place the held block on the ground.
Parameters:
block(str): The name of the block to put down
Preconditions:
Robot must be holding the specified block
A free ground position must be available
4. stack
Place the held block on top of another block.
Parameters:
block_x(str): The block to place (currently held)block_y(str): The block to stack on
Preconditions:
Robot must be holding block x
Block y must be clear
5. status
Get the current state of the simulation.
Returns:
Complete JSON object with all block positions, stack configurations, and robot state
6. rules
Get the complete description of blocksworld rules and constraints.
Returns:
Markdown-formatted text describing the environment, rules, and available actions
7. verify_plan
Verify a multi-step plan without executing it.
Parameters:
plan(PlanRequest): A sequence of actions to verify
Returns:
Success message if the plan is verified, or detailed error message indicating which step fails
Note: execute_plan is disabled by default to encourage LLMs to execute actions step-by-step for better reasoning.
π Example Usage
Here's how an LLM might use these tools to solve a simple problem:
User: "Stack block A on top of block B"
LLM thought process:
1. Call status() to see current state
2. Call rules() to understand constraints
3. Determine plan: pick_up(A) β stack(A, B)
4. Call verify_plan([pick_up(A), stack(A, B)]) to verify
5. Execute: pick_up(A)
6. Execute: stack(A, B)
7. Confirm successπ§ Configuration
Changing the Simulation API URL
By default, the MCP server connects to http://localhost:5001. To change this, edit src/blocksworld_simulation_mcp_server/mcp_server.py:
SIM_API = "http://localhost:5001" # Change this lineπ Architecture
βββββββββββββββββββββββ MCP Protocol ββββββββββββββββββββ
β LLM (Claude) βββββββββββββββββββββββββββββββββββΊβ MCP Server β
β β Tool Calls & Responses β (This Repo) β
βββββββββββββββββββββββ ββββββββββββββββββββ
β
HTTP REST API
β
βΌ
ββββββββββββββββββββ
β Blocksworld β
β Simulation β
β (localhost:5001)β
ββββββββββββββββββββThe MCP server acts as a bridge between:
LLMs that speak the Model Context Protocol
Blocksworld Simulation that exposes a REST API
π Related Projects
Blocksworld Simulation - The visual simulation environment this server connects to
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
This server cannot be deployed
Maintenance
Related MCP Connectors
Your personal world model for any agent.
Context and control for any AI. Agent identity, scoped access, and proof across tools.
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
Calibrated world model for AI agents. 40 tools: world state, markets, trading. Kalshi + Polymarket.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to interact with and control Roblox Studio instances in real-time through the Model Context Protocol. It provides a unified tool for building, scripting, and manipulating 3D worlds with over 90 operations including instance management and Luau scripting.14 npm-
- AlicenseNot gradedqualityDmaintenanceA bridge that enables any LLM to access and interact with documented REST APIs through the Model Context Protocol (MCP).14 npm6MIT
- AlicenseNot gradedqualityBmaintenanceEnables LLMs to control Blender for 3D scene creation, object manipulation, material assignment, shader configuration, modifier application, keyframing, and rendering via the Model Context Protocol.2GPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to understand, query, and manipulate Honeybee building energy models through natural language via the Model Context Protocol.18GPL 3.0