MCP 服务器

simple-rail-mcp

Enables controlling linear rails via natural language commands through Claude AI in Cursor, supporting HTTP, serial, and G-code controllers with configurable positions.

README

Simple Rail MCP Server

MCP (Model Context Protocol) server for controlling linear rails via natural language through Claude AI in Cursor.

What This Does

Control your linear rail with natural language:

You: "Move the rail to position 500mm"
Claude: ✅ Rail moved to 500mm

You: "Move rail to opentrons station"
Claude: ✅ Rail at opentrons station

Supported Controllers

✅ UW PICO 5.09 - HTTP API with G-code forwarding (pre-configured)
✅ Any HTTP API that accepts commands
✅ Serial port controllers
✅ Python script wrappers
✅ G-code senders

Quick Start

1. Install

npm install

2. Configure

Edit index.js lines 32-37:

// For UW PICO controller:
this.RAIL_IP = "192.168.1.101";      // Your controller IP
this.RAIL_PORT = "80";
this.RAIL_ENDPOINT = "/command";
this.COMMAND_TEMPLATE = "G0 X{position} F1000";

Set your positions (lines 41-47):

this.POSITIONS = {
  "pickup_station": 0,
  "opentrons": 500,
  "plate_reader": 750,
  "storage": 1000,
  "home": 0
};

3. Add to Cursor

Edit .cursor/mcp.json:

{
  "mcpServers": {
    "rail": {
      "command": "node",
      "args": ["/absolute/path/to/simple-rail-mcp/index.js"],
      "env": {
        "RAIL_IP": "192.168.1.101"
      }
    }
  }
}

4. Restart Cursor

5. Use!

"Move the rail to opentrons"
"Move rail to 500mm"
"Move to home position"

Configuration Options

For UW PICO 5.09 Controller

Your controller has an HTTP API that forwards G-code via UART.

Test with curl:

curl -X POST http://192.168.1.101/command \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "cmd=G0 X500 F1000"

Config:

this.RAIL_IP = "192.168.1.101";
this.RAIL_PORT = "80";
this.RAIL_ENDPOINT = "/command";
this.COMMAND_TEMPLATE = "G0 X{position} F1000";

For Other HTTP APIs

If your controller uses different endpoints/formats:

this.RAIL_IP = "192.168.1.100";
this.RAIL_ENDPOINT = "/api/move";
this.COMMAND_TEMPLATE = '{"position": {position}}';  // JSON format

Position Configuration

Edit the POSITIONS object to match your physical setup:

this.POSITIONS = {
  "station_a": 0,        // First position (mm)
  "station_b": 250,      // Second position (mm)
  "station_c": 500,      // Third position (mm)
  "home": 0              // Home position
};

Timing Configuration

Adjust wait time after movement (line 54):

this.MOVE_WAIT_TIME = 5;  // Wait 5 seconds after sending command

If your rail is faster or slower, adjust accordingly.

Environment Variables

You can override config with environment variables:

{
  "mcpServers": {
    "rail": {
      "command": "node",
      "args": ["/path/to/index.js"],
      "env": {
        "RAIL_IP": "192.168.1.101",
        "RAIL_PORT": "80"
      }
    }
  }
}

API Reference

Tool: `move_rail_and_wait`

Move linear rail to a position and wait for completion.

Parameters:

position (string) - Named position from POSITIONS config
- Example: "opentrons", "pickup_station", "home"
position_number (number) - Numeric position in mm
- Example: 500, 750.5
wait_seconds (number) - Override default wait time
- Default: MOVE_WAIT_TIME from config

Examples:

// Via Claude in natural language:
"Move rail to opentrons"
"Move rail to 500mm"
"Move to home position"

// Direct tool call (from code):
move_rail_and_wait({ position: "opentrons" })
move_rail_and_wait({ position_number: 500 })
move_rail_and_wait({ position: "storage", wait_seconds: 10 })

G-code Reference

Common G-code commands for linear rails:

Command	Description
`G0 X500 F1000`	Move to 500mm at 1000mm/min (fast)
`G1 X500 F500`	Move to 500mm at 500mm/min (controlled)
`G28 X`	Home X axis
`G90`	Set absolute positioning mode
`G91`	Set relative positioning mode
`G92 X0`	Set current position as zero
`M114`	Query current position
`M400`	Wait for all moves to complete

Troubleshooting

Cannot connect to controller

Check IP:
```
ping 192.168.1.101
```
Test endpoint:
```
curl http://192.168.1.101/command
```
Check firewall - Allow Node.js/Cursor through firewall

Rail doesn't move

Test G-code manually:

curl -X POST http://192.168.1.101/command -d "cmd=G28 X"  # Home first
curl -X POST http://192.168.1.101/command -d "cmd=G0 X500 F1000"

Check positioning mode:

curl -X POST http://192.168.1.101/command -d "cmd=G90"  # Absolute mode

Verify position is in range - Check your rail's physical limits

Wrong position

Check units - Make sure G21 (mm) is set:

curl -X POST http://192.168.1.101/command -d "cmd=G21"

Calibrate positions - Measure actual distances and update POSITIONS

Home the rail first:

curl -X POST http://192.168.1.101/command -d "cmd=G28 X"

MCP server not loading in Cursor

Test manually:
```
node index.js
```
Check Node version:
```
node --version  # Should be ≥18.0.0
```
Check path in .cursor/mcp.json - Use absolute path
Restart Cursor completely

Advanced: Custom Controller Support

To add support for other controller types, modify the sendHttpCommand method:

async sendHttpCommand(position) {
  const gcode = this.COMMAND_TEMPLATE.replace('{position}', position);
  const url = `http://${this.RAIL_IP}:${this.RAIL_PORT}${this.RAIL_ENDPOINT}`;
  
  // Customize request format here
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'  // Change as needed
    },
    body: JSON.stringify({ command: gcode })  // Change format
  });
  
  // Customize response parsing here
  const data = await response.json();
  return data;
}

Integration Example

Use with other MCP servers for full automation:

// Example: Pick up plate and move to Opentrons
"Move rail to pickup station"  // This MCP server
"Run VLA pickup script"        // VLA MCP server
"Move rail to opentrons"       // This MCP server
"Upload purple_mixing.py"      // Opentrons MCP server
"Start the protocol"           // Opentrons MCP server