Pybullet MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with PyBullet physics simulations. Build physics-based projects through natural language interactions with AI agents.

- 37 MCP Tools: Comprehensive API for physics simulation control including robot joint control
- Simulation Management: Create and manage multiple independent physics simulations with configurable gravity
- Object Manipulation: Add primitive shapes (box, sphere, cylinder, capsule) and URDF models with full property control
- Robot Control: Query joint information, control motors (position/velocity/torque), and calculate inverse kinematics
- Physics Control: Apply forces, torques, and step through simulations with configurable timesteps
- State Persistence: Save and load complete simulation states to/from JSON files
- Constraints: Create joints between objects (fixed, prismatic, spherical)
- Collision Detection: Query contact points with detailed collision information
- Visualization: Optional GUI mode with debug visualization and camera control
- Error Handling: Comprehensive validation with descriptive error messages

- Coordinate Requirements: All vectors must be provided as complete 3D coordinates [x, y, z]

- Gravity:[0, 0, -9.81](not[-9.81])
- Positions:[x, y, z](not[x, y]or[x])
- Forces/Torques:[fx, fy, fz](not[fx])
- Orientations:[x, y, z, w]quaternion (not[w])

- Python 3.9 or higher
- pip package manager
- Virtual environment (recommended)
- Create and activate a virtual environment:

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

- For development (includes testing tools):

pip install fastmcp pybullet pytest hypothesis pytest-cov

Check that the required packages are installed:

python -c "import pybullet; import mcp; print('Installation successful!')"

SeeQUICKSTART.mdfor detailed instructions on:

source venv/bin/activate # On Windows: venv\Scripts\activate python -m src.server

Create a new physics simulation with Earth gravity

This callscreate_simulationwith gravity[0, 0, -9.81].

Important: Gravity must be a 3D vector. The server accepts shorthand like[-9.81]and expands it to[0, 0, -9.81].

Add a red box at position (0, 0, 1) with dimensions 0.5x0.5x0.5 and mass 1.0

This callsadd_boxto create a box object. Position is automatically expanded to[0, 0, 1].

Add a sphere at (2, 0, 1) with radius 0.3

This callsadd_sphereto create a sphere.

Note: Mass must be positive. For static objects (like ground planes), use large mass values (e.g., 1000).

This callsstep_simulationwith steps=100.

What is the position and velocity of object 0?

This callsget_object_stateto retrieve position, orientation, and velocities.

This callsapply_forceto push the object.

Save the current simulation state to simulation.json

This callssave_simulationto persist the state.

Load the simulation from simulation.json

This callsload_simulationto restore the saved state.

To use this server with Cursor or any other MCP-compatible client, add the following to your MCP configuration file:

{ "mcpServers": { "pybullet": { "url": "http://localhost:8000/mcp", "disabled": false } } }

The server runs HTTP transport by default. You can change the transport method by editing the entry point inserver.py:

if __name__ == "__main__": mcp.run(transport="http", port=8000)

Restart your MCP client after updating the configuration.

The server exposes 37 tools through the MCP protocol:

-

create_simulation: Initialize a new physics simulation with configurable gravity and optional GUI

- Parameters:gravity(list[float], default: [0, 0, -9.81]),gui(bool, default: false)
- Returns: simulation_id, gravity, gui_enabled

list_simulations: Get all active simulation IDs

destroy_simulation: Clean up and remove a simulation

- Parameters:sim_id(str)
- Returns: confirmation message

step_simulation: Advance simulation by one or more timesteps

- Parameters:sim_id(str),steps(int, default: 1)
- Returns: simulation_id, steps_taken, current_time

set_timestep: Configure the timestep duration for a simulation

- Parameters:sim_id(str),timestep(float)
- Returns: confirmation message

-

add_box: Add a box shape to the simulation

- Parameters:sim_id,dimensions(list[float]),position(list[float]),mass(float, default: 1.0),color(list[float], optional)
- Returns: object_id, shape, position

add_sphere: Add a sphere shape to the simulation

- Parameters:sim_id,radius(float),position(list[float]),mass(float, default: 1.0),color(list[float], optional)
- Returns: object_id, shape, position

add_cylinder: Add a cylinder shape to the simulation

- Parameters:sim_id,radius(float),height(float),position(list[float]),mass(float, default: 1.0),color(list[float], optional)
- Returns: object_id, shape, position

add_capsule: Add a capsule shape to the simulation

- Parameters:sim_id,radius(float),height(float),position(list[float]),mass(float, default: 1.0),color(list[float], optional)
- Returns: object_id, shape, position

load_urdf: Load a robot model from a URDF file

- Parameters:sim_id,file_path(str),position(list[float]),orientation(list[float], optional)
- Returns: object_id, file_path, position

set_object_pose: Update object position and orientation

- Parameters:sim_id,object_id(int),position(list[float]),orientation(list[float])
- Returns: confirmation message

get_object_state: Query complete object state

- Parameters:sim_id,object_id(int)
- Returns: position, orientation, linear_velocity, angular_velocity

apply_force: Apply a force vector to an object

- Parameters:sim_id,object_id(int),force(list[float]),position(list[float], optional)
- Returns: confirmation message

apply_torque: Apply rotational force to an object

- Parameters:sim_id,object_id(int),torque(list[float])
- Returns: confirmation message

set_object_velocity: Set an object's linear and/or angular velocity directly

- Parameters:sim_id,object_id(int),linear_velocity(list[float], optional),angular_velocity(list[float], optional)
- Returns: confirmation message

change_dynamics: Modify object physics properties at runtime

- Parameters:sim_id,object_id(int),link_index(int, default: -1),mass(float, optional),lateral_friction(float, optional),spinning_friction(float, optional),rolling_friction(float, optional),restitution(float, optional),linear_damping(float, optional),angular_damping(float, optional),contact_stiffness(float, optional),contact_damping(float, optional)
- Returns: confirmation message

get_dynamics_info: Query current dynamic properties of an object

- Parameters:sim_id,object_id(int),link_index(int, default: -1)
- Returns: mass, lateral_friction, local_inertia_diagonal, restitution, rolling_friction, spinning_friction, contact_damping, contact_stiffness, body_type, collision_margin

-

ray_test: Cast a single ray to detect obstacles and measure distances

- Parameters:sim_id,ray_from(list[float]),ray_to(list[float])
- Returns: hit (bool), object_id, link_index, hit_fraction, hit_position, hit_normal

ray_test_batch: Cast multiple rays efficiently for lidar/sensor simulation

- Parameters:sim_id,rays_from(list[list[float]]),rays_to(list[list[float]])
- Returns: list of hit results (same fields as ray_test per ray)

-

compute_view_matrix: Compute view matrix from camera eye/target/up vectors

- Parameters:camera_eye_position(list[float]),camera_target_position(list[float]),camera_up_vector(list[float])
- Returns: view matrix as list of 16 floats

compute_view_matrix_from_yaw_pitch: Compute view matrix from spherical coordinates (orbit camera)

- Parameters:distance(float),yaw(float),pitch(float),target_position(list[float]),up_axis_index(int, default: 2)
- Returns: view matrix as list of 16 floats

compute_projection_matrix: Compute projection matrix from camera parameters