simple-rail-mcp

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: ``bash curl -X POST http://192.168.1.101/command \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "cmd=G0 X500 F1000" ``

Config: ``javascript 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

1. Check IP:

   ping 192.168.1.101

1. Test endpoint:

   curl http://192.168.1.101/command

1. Check firewall - Allow Node.js/Cursor through firewall

Rail doesn't move

1. 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"

1. Check positioning mode:

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

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

Wrong position

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

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

1. Calibrate positions - Measure actual distances and update POSITIONS

1. Home the rail first:

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

MCP server not loading in Cursor

1. Test manually:

   node index.js

1. Check Node version:

   node --version  # Should be ≥18.0.0

1. Check path in .cursor/mcp.json - Use absolute path

1. 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

Claude AI automatically orchestrates all systems!

Requirements

• Node.js ≥18.0.0
• Cursor IDE with MCP support
• Linear rail with HTTP/serial/script control

License

MIT

Contributing

Issues and pull requests welcome!

Credits

• Model Context Protocol - Anthropic
• Claude AI - Natural language orchestration
• Cursor IDE - Development environment

---

Questions? Open an issue or check the troubleshooting guide.