Opentrons

A Model Context Protocol (MCP) server that provides 67 tools for controlling Opentrons OT-2 and Flex robots. This server enables AI assistants like Claude (via Cursor, Cline, or other MCP clients) to directly control your Opentrons robot through natural language commands.

Features

• 🤖 67 Opentrons Control Tools - Complete API coverage for robot control
• 💡 Protocol Management - Upload, run, pause, stop, and manage protocols
• 🏠 Robot Control - Home, move, control lights, check status
• 🧪 Labware Management - Manage tip racks, plates, reservoirs, and modules
• 📊 Real-time Monitoring - Check run status, commands, and robot health
• 🎯 Precision Control - Fine-grained control over robot movements
• 🔧 Calibration Tools - Labware offsets and calibration management
• 🌐 Network Discovery - Find and connect to robots on your network

Quick Start

Local Installation (Recommended for Personal Use)

1. Clone the repository:

git clone https://github.com/global-mysterysnailrevolution/Opentrons-mcp-server.git
cd Opentrons-mcp-server

2. Install dependencies:

npm install

3. Configure your MCP client (e.g., Cursor, Cline):

Add to your MCP settings file:

For Cursor (~/.cursor/mcp_config.json or %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json):

{
  "mcpServers": {
    "opentrons-robot": {
      "command": "node",
      "args": ["/full/path/to/Opentrons-mcp-server/index.js"],
      "env": {
        "ROBOT_IP": "192.168.16.38"
      }
    }
  }
}

For Cline (VS Code extension settings):

{
  "opentrons-robot": {
    "command": "node",
    "args": ["C:\\Users\\YourUsername\\Opentrons-mcp-server\\index.js"],
    "env": {
      "ROBOT_IP": "192.168.16.38"
    }
  }
}

4. Find your robot's IP address:

   • Open the Opentrons app
   • Go to Robot Settings → Networking
   • Note the IP address (e.g., 192.168.16.38)

5. Restart your MCP client (Cursor/VS Code) to load the server

6. Start using it! Ask Claude to:

   • "Check if my Opentrons robot is connected"
   • "Home the robot"
   • "Turn on the lights"
   • "Upload this protocol and run it"
   • "Pick up tips from row 4 and transfer liquid"

Deployment Options

Option 1: Local MCP Server (Best for Security & Speed)

Pros:

• ✅ Direct connection to robot on local network
• ✅ No internet required
• ✅ Fastest response time
• ✅ Most secure (no external access)

Cons:

• ❌ Only works on local network
• ❌ Must be running when you want to use it

Setup: Follow the Quick Start instructions above.

Option 2: ngrok Tunnel (Remote Access)

Pros:

• ✅ Access robot from anywhere
• ✅ Easy setup
• ✅ Works with existing MCP server

Cons:

• ❌ Requires ngrok account
• ❌ Security risk (anyone with link can access)
• ❌ May have latency

Setup:

# Install ngrok
npm install -g ngrok

# Start the HTTP wrapper server
node http-server.js

# In another terminal, expose it
ngrok http 3000

# Use the ngrok URL in your MCP settings

Option 3: Railway Deployment (Web Interface)

Note: Railway deployment is for the web interface, not the MCP server. For AI assistant control, use Option 1 or 2.

Setup:

1. Create a Railway account at https://railway.app
2. Connect your GitHub repository
3. Set environment variables:
   • ROBOT_IP: Your robot's IP address
   • ROBOT_PORT: 31950
4. Deploy!

This gives you a web interface but NOT MCP integration.

Option 4: VPN + Local MCP (Recommended for Remote Work)

Pros:

• ✅ Secure remote access
• ✅ Full MCP functionality
• ✅ Fast and reliable

Cons:

• ❌ Requires VPN setup (e.g., Tailscale, ZeroTier)

Setup:

1. Install Tailscale/ZeroTier on computer with robot
2. Connect remotely via VPN
3. Use robot's VPN IP in MCP settings
4. Use local MCP server (Option 1)

Using with Dedalus Labs AI

Dedalus Labs AI supports MCP servers for enhanced AI capabilities. Here's how to connect your Opentrons robot:

Method 1: Direct Integration (If Supported)

1. Export your MCP configuration:

{
  "opentrons-robot": {
    "command": "node",
    "args": ["/path/to/index.js"],
    "env": {
      "ROBOT_IP": "192.168.16.38"
    }
  }
}

2. In Dedalus Labs AI:
   • Go to Settings → Integrations → MCP Servers
   • Add new MCP server
   • Paste configuration
   • Save and restart

Method 2: Via HTTP Wrapper (Remote Access)

1. Start the HTTP wrapper:

node http-server.js

2. Expose via ngrok:

ngrok http 3000

3. Configure Dedalus Labs AI:

   • Add HTTP endpoint integration
   • Use ngrok URL
   • Set headers: Content-Type: application/json

4. Available endpoints:

   • POST /tool/robot_health - Check robot health
   • POST /tool/upload_protocol - Upload protocol
   • POST /tool/home_robot - Home robot
   • POST /tool/control_lights - Control lights
   • And 63 more tools!

Method 3: Custom API Integration

If Dedalus Labs AI supports custom APIs:

1. Use the Railway deployment (web interface)
2. Point Dedalus to your Railway URL
3. Use REST API endpoints directly

Available MCP Tools (67 Total)

Core Robot Control

• robot_health - Check robot connectivity and status
• home_robot - Home robot axes
• control_lights - Turn lights on/off
• get_robot_position - Get current position
• move_robot - Move to specific position

Protocol Management

• upload_protocol - Upload protocol files
• get_protocols - List all protocols
• create_run - Create protocol run
• control_run - Play/pause/stop runs
• get_run_status - Check run status
• get_runs - List all runs

Labware & Calibration

• list_labware - List deck labware
• add_labware - Add labware to deck
• remove_labware - Remove labware
• list_labware_offsets - Get calibration offsets
• create_labware_offset - Set calibration offsets
• delete_labware_offset - Remove offsets

Instruments & Modules

• list_instruments - List attached pipettes
• get_instrument - Get pipette details
• list_modules - List attached modules
• get_module - Get module details
• get_module_data - Get module sensor data

Advanced Features

• execute_command - Execute direct commands
• list_commands - View command history
• get_command - Get command details
• analyze_protocol - Analyze protocol requirements
• get_system_info - Get system information

Data Management

• upload_data_file - Upload CSV data files
• list_data_files - List data files
• delete_data_file - Delete data files

OT-2 Specific

• create_session - Create calibration session
• execute_session_command - Run calibration commands
• get_calibration_status - Check calibration
• start_calibration - Begin calibration process

Flex Specific

• get_flex_deck_configuration - Get Flex deck setup
• set_flex_deck_configuration - Configure Flex deck
• get_error_recovery_settings - Error recovery config
• set_error_recovery_policy - Set error handling
• list_maintenance_runs - Maintenance operations
• list_subsystems - Subsystem control

And 30+ more tools for complete robot control!

Environment Variables

• ROBOT_IP - Your robot's IP address (required)
• ROBOT_PORT - Robot's HTTP API port (default: 31950)

Example Protocols

This repository includes example protocols:

• complete_liquid_transfer_dispense_top.py - Full liquid transfer with calibration offsets
• hold_above_4th_row_tips.py - Position verification protocol
• And many more examples!

Troubleshooting

Robot Not Responding

• Check robot IP address is correct
• Ensure robot is on same network (or VPN)
• Verify robot's HTTP API is running (check Opentrons app)
• Ping the robot: ping 192.168.16.38

MCP Server Not Loading

• Check MCP config file path is correct
• Verify Node.js is installed: node --version
• Check file permissions on index.js
• Restart your MCP client (Cursor/VS Code)

Protocol Upload Fails

• Ensure protocol syntax is correct
• Check robot has available storage
• Verify file is .py or .json format
• Try uploading via Opentrons app first

Connection Issues from Remote

• Check ngrok tunnel is running
• Verify firewall allows connections
• Test with curl: curl http://your-ngrok-url.ngrok.io/health

Security Considerations

⚠️ IMPORTANT: This server provides full control over your robot.

For Local Use:

• ✅ Safe - only accessible on local network
• ✅ No external exposure

For Remote Use:

• ⚠️ Use authentication (add auth middleware)
• ⚠️ Use HTTPS/TLS encryption
• ⚠️ Restrict IP access if possible
• ⚠️ Monitor access logs
• ⚠️ Use VPN when possible instead of public exposure

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

Support

• Issues: Open a GitHub issue
• Discussions: Use GitHub Discussions
• Documentation: See Opentrons API docs

License

MIT License - Feel free to modify and use for your projects!

Acknowledgments

• Built on the Model Context Protocol
• Uses Opentrons HTTP API
• Inspired by the need for AI-controlled lab automation

---

Made with ❤️ for the lab automation community