mcp

GraspGen MCP Server

A Model Context Protocol (MCP) server that enables LLMs (Claude, Cursor, etc.) to generate 6-DOF robotic grasp poses using GraspGen.

┌─────────────────────┐        MCP (stdio)        ┌─────────────────────┐       ZMQ (tcp)       ┌─────────────────────┐
│  LLM / AI Agent     │  ◀─── tool calls ───────▶  │  MCP Server         │  ── point cloud ───▶  │  GraspGen Server    │
│  (Cursor, Claude…)  │                            │  (this package)     │  ◀── grasps ────────  │  (GPU, model loaded)│
└─────────────────────┘                            └─────────────────────┘                       └─────────────────────┘

The MCP server is a lightweight bridge — it requires no CUDA or model weights. It connects to a running GraspGen ZMQ inference server and exposes its capabilities as MCP tools that any LLM agent can call.

Available Tools

Tool	Description
generate_grasps_from_mesh	Generate 6-DOF grasp poses from a 3D mesh file (.obj, .stl, .ply, .glb). Samples a point cloud from the mesh surface and runs GraspGen inference.
generate_grasps_from_point_cloud	Generate 6-DOF grasp poses from a point cloud file (.npy, .npz, .ply, .pcd).
visualize_grasps	Generate grasps and visualize them interactively in a 3D viser web viewer. Accepts a mesh or point cloud file. Grasps are color-coded by confidence (green=high, red=low).
graspgen_health_check	Check if the GraspGen inference server is running and responsive.
graspgen_server_info	Get metadata about the server: loaded gripper name, model config, etc.

Prerequisites

The GraspGen ZMQ server must be running. See the client-server/README.md for setup instructions.

Quick start (Docker):

# From the GraspGen repo root:
MODELS_DIR=/path/to/GraspGenModels docker compose -f docker/compose.serve.yml up --build

Quick start (local):

python client-server/graspgen_server.py --gripper_config /path/to/GraspGenModels/checkpoints/graspgen_robotiq_2f_140.yml

Installation

Using uv (recommended)

cd GraspGen/mcp
uv venv --python 3.10 .venv && source .venv/bin/activate
uv pip install -e .

Using pip

cd GraspGen/mcp
pip install -e .

Configuration

Configure for Cursor

Add the following to .cursor/mcp.json in your workspace (or to your global Cursor settings). Make sure to edit the --directory entry.

{
  "mcpServers": {
    "graspgen": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/GraspGen/mcp",
        "mcp-server-graspgen"
      ],
      "env": {
        "GRASPGEN_HOST": "localhost",
        "GRASPGEN_PORT": "5556"
      }
    }
  }
}

Or if you installed with pip:

{
  "mcpServers": {
    "graspgen": {
      "command": "python",
      "args": ["-m", "mcp_server_graspgen"],
      "env": {
        "GRASPGEN_HOST": "localhost",
        "GRASPGEN_PORT": "5556"
      }
    }
  }
}

Configure for Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "graspgen": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/GraspGen/mcp",
        "mcp-server-graspgen"
      ],
      "env": {
        "GRASPGEN_HOST": "localhost",
        "GRASPGEN_PORT": "5556"
      }
    }
  }
}

Configure for VS Code

Add to .vscode/mcp.json in your workspace:

{
  "mcp": {
    "servers": {
      "graspgen": {
        "command": "uv",
        "args": [
          "run",
          "--directory", "/absolute/path/to/GraspGen/mcp",
          "mcp-server-graspgen"
        ],
        "env": {
          "GRASPGEN_HOST": "localhost",
          "GRASPGEN_PORT": "5556"
        }
      }
    }
  }
}

Custom Server Address

If the GraspGen ZMQ server is on a different host or port, set the environment variables:

• GRASPGEN_HOST — default: localhost
• GRASPGEN_PORT — default: 5556

Or pass them as CLI arguments:

mcp-server-graspgen --host 192.168.1.100 --port 5557

Example LLM Interactions

Once configured, an LLM can naturally call GraspGen:

User: "Generate grasps for the box mesh at /models/sample_data/meshes/box.obj"

LLM → generate_grasps_from_mesh: {"mesh_file": "/models/sample_data/meshes/box.obj", "mesh_scale": 1.0}

Response: "Generated 100 grasps. Confidence range: 0.7234 – 0.9812. Top grasp at position (0.012, -0.003, 0.045) with confidence 0.9812..."

User: "Is the grasp server running?"

LLM → graspgen_health_check

Response: "GraspGen server status: ok"

Debugging

Use the MCP inspector to test the server:

cd GraspGen/mcp
npx @modelcontextprotocol/inspector uv run mcp-server-graspgen