RobotArm MCP P340

English | 中文

概述

这是一个模型上下文协议（MCP）服务器实现，为ElephantRobotics MyCobot系列机械臂（特别是针对ultraArmP340进行了优化）提供自然语言控制。该服务器通过对话式AI使机械臂的控制变得简单，让每个人都能轻松使用机器人技术。

特性

• 🤖 支持多种MyCobot型号（ultraArmP340, MyCobot280, MyCobot320）
• 🎮 通过MCP协议进行自然语言控制
• 🔧 无需实际硬件的开发模拟模式
• 🛡️ 包括紧急停止在内的安全功能
• 📊 实时状态监控

组件

工具

服务器提供了以下控制工具：

连接管理

• connect_robot - 连接到机械臂
  • 输入: model (字符串): 机器人型号
  • 输入: port (字符串): 串行端口
  • 返回: 连接状态

状态监控

• get_robot_status - 获取当前机器人状态
  • 返回: 当前角度、坐标、夹爪/泵状态、运动状态

运动控制

• move_to_angles - 将关节移动到特定角度

  • 输入: angles (数组): 每个关节的目标角度
  • 输入: speed (整数): 移动速度
  • 返回: 移动确认

• move_to_coords - 移动到特定坐标

  • 输入: coords (数组): 目标坐标
  • 输入: speed (整数): 移动速度
  • 返回: 移动确认

末端执行器控制

• control_gripper - 控制夹爪开合
• control_pump - 控制吸盘开关

系统命令

• go_zero - 使机器人返回零位
• emergency_stop - 紧急停止所有运动

高级运动控制

• execute_action_sequence - 执行自定义动作序列
  • 输入: sequence_name (字符串): 序列的描述性名称
  • 输入: actions (数组): 动作列表，每个动作包含:
    • type: 动作类型 ("angles", "coords", "gripper", "pump", "wait")
    • angles/coords: 目标位置（基于类型）
    • speed: 移动速度（可选，默认50）
    • duration: 动作持续时间（秒）（可选）
    • gripper_action: "open" 或 "close" （对于夹爪类型）
    • pump_action: "on" 或 "off" （对于泵类型）
  • 输入: default_interval (浮点数): 动作之间的默认间隔（可选，默认0.5秒）
  • 返回: 执行状态及完成的动作数量
  • 注意: 此工具通过动作序列实现复杂行为，如猫玩耍、画圆、跳舞和自定义手势

资源

• status://current - 实时机器人状态信息

提示

• robot_control_guide - 交互式机器人控制指南

  • 参数: task (任务类型)
  • 提供逐步指导

• design_action_sequence - 自定义动作序列设计模板

  • 参数:
    • task_description: 任务描述（例如，“跳舞”、“猫玩耍”、“按摩”）
  • 提供结构化的动作序列设计指导
  • 帮助设计平滑、连续且具有适当时间的动作

快速开始

安装

1. 确保已安装Python 3.10
2. 安装依赖项：
   bash

pip install robotarm-mcp-p340

Cursor配置

有三种方法可以在Cursor中配置MCP：

方法1：Python模块配置（推荐用于已安装的包）

如果你通过pip安装了包：
python

{
  "mcpServers": {
    "mycobot": {
      "command": "Fill in the python path under the virtual environment folder where robotarm-mcp-p340 is installed",
      "args": ["-u", "-m", "mycobot_mcp"],
      "env": {
        "SIMULATE": "1"
      }
    }
  }
}

Example:

{
  "mcpServers": {
    "mycobot": {
      "command": "D:\\anaconda3\\envs\\test-robotarm\\python.exe",
      "args": ["-u", "-m", "mycobot_mcp"],
      "env": {
        "SIMULATE": "1"
      }
    }
  }
}

方法2：开发配置（适用于从GitHub克隆）

如果你从GitHub克隆并正在开发：
python

{
  "mcpServers": {
    "mycobot": {
      "command": "Fill in the python path under the project's virtual environment folder",
      "args": [
        "-u",
        "-m",
        "mycobot_mcp"
      ],
      "env": {
        "SIMULATE": "1",
        "PYTHONPATH": "Fill in the absolute path to the src folder"
      },
      "cwd": "Fill in the absolute path to the project root"
    }
  }
}

Example:

{
  "mcpServers": {
    "mycobot": {
      "command": "D:\\Anaconda3\\envs\\mycobot-mcp\\python.exe",
      "args": [
        "-u",
        "-m",
        "mycobot_mcp"
      ],
      "env": {
        "SIMULATE": "1",
        "PYTHONPATH": "D:\\AI\\mycobot-mcp\\src"
      },
      "cwd": "D:\\AI\\mycobot-mcp"
    }
  }
}

重要提示：

• "SIMULATE": "1" 用于无硬件的模拟测试。对于实际设备测试，请将SIMULATE设置为"0"- 方法2需要在项目的虚拟环境中从requirements.txt安装项目依赖
• 必须使用-u标志来禁用Python输出缓冲
• 设置PYTHONPATH以包含src目录
• 根据您的安装调整路径

方法3：批处理文件配置（Windows）

1. 创建一个批处理文件start_mcp_server.bat：
   batch

@echo off
cd /d D:\AI\mycobot-mcp
set PYTHONPATH=D:\AI\mycobot-mcp\src
set SIMULATE=1
D:\Anaconda3\envs\mycobot-mcp\python.exe -u -m mycobot_mcp

1. 配置Cursor：
   batch

{
  "mcpServers": {
    "mycobot": {
      "command": "D:\\AI\\mycobot-mcp\\start_mcp_server.bat"
    }
  }
}

配置步骤

1. 打开Cursor设置（Ctrl+,）
2. 搜索"MCP"或"Model Context Protocol"
3. 使用上述方法之一添加配置
4. 重启Cursor以应用更改

验证

成功配置后，您应该看到：

• ✅ MCP状态中显示“9个工具已启用”
• ✅ 聊天中可用的工具：connect_robot、get_robot_status等

使用示例

1. 连接到机器人：

   • “连接到我的ultraArm P340机器人”
   • “初始化COM3端口上的机器人”（根据您的设备实际COM端口号进行调整，默认为3）

2. 基本移动：

   • “将机械臂移动到位置[200, 0, 150]”
   • “将关节角度设置为[45, 30, -20]”
   • “返回原点”

3. 夹爪控制：

   • “打开夹爪”
   • “关闭夹爪以拾取物体”
   • “开启吸泵”

4. 复杂任务：

   • “用机械臂和我的猫玩耍”
   • “在桌子上画一个圆圈”
   • “教我如何写汉字”
   • “让机器人随着音乐跳舞”
   • “创建自定义挥手序列”

开发模式

设置SIMULATE=1以在没有硬件的情况下测试：
bash

export SIMULATE=1  # Linux/Mac
set SIMULATE=1     # Windows

故障排除

如果工具未正确加载：

1. 检查Cursor中的MCP日志：

   • 查看 → 输出 → 选择“MCP”通道
   • 查找错误消息

2. 本地测试服务器：
   bash

   # For installed package
   python -m mycobot_mcp
   
   # For development (from project root)
   cd D:\AI\mycobot-mcp
   set PYTHONPATH=src
   python -m mycobot_mcp
   

3. 常见问题及解决方案：

   • "No module named 'mycobot_mcp'":

     • 对于开发：确保PYTHONPATH包括src文件夹
     • 对于已安装：从项目根目录运行pip install -e .

   • "Tools not loading":

     • 确保使用的是-m mycobot_mcp而不是-m mycobot_mcp.server
     • 在开发模式下验证cwd设置为项目根目录

   • 配置提示：

     • ✅ 始终使用-u标志以实现无缓冲输出
     • ✅ 将PYTHONPATH设置为src文件夹（不是src/mycobot_mcp）
     • ✅ 使用cwd设置开发时的工作目录
     • ❌ 不要直接运行server.py

安全指南

⚠️ 重要安全信息：

1. 始终确保机器人周围有清晰的工作空间
2. 将手和物体远离运动部件
3. 如果出现意外行为，请使用紧急停止
4. 测试新动作时从慢速开始
5. 切勿在人类身上使用按摩演示
6. 始终监督与宠物的互动

许可

此MCP服务器基于MIT许可。有关详细信息，请参阅LICENSE文件。

---

概述

RobotArm MCP P340 是一个基于模型上下文协议（MCP）的服务器实现，为大象机器人 MyCobot 系列机械臂提供自然语言控制功能（特别针对 ultraArmP340 进行了优化）。通过对话式 AI 控制机械臂，让机器人技术人人可用。

功能特点

• 🤖 支持多种 MyCobot 型号（ultraArmP340、MyCobot280、MyCobot320）
• 🎮 通过 MCP 协议实现自然语言控制机械臂
• 🔧 模拟模式支持无硬件开发
• 🛡️ 包含紧急停止等安全功能
• 📊 实时状态监控

组件说明

工具（Tools）

服务器提供以下控制工具：

连接管理

• connect_robot - 连接机械臂
  • 输入：model（字符串）：机器人型号
  • 输入：port（字符串）：串口号
  • 返回：连接状态

状态监控

• get_robot_status - 获取机器人当前状态
  • 返回：当前角度、坐标、夹爪/吸泵状态、运动状态

运动控制

• move_to_angles - 移动关节到指定角度- 输入：angles（数组）：各关节目标角度

  • 输入：speed（整数）：运动速度
  • 返回：运动确认

• move_to_coords - 移动到指定坐标

  • 输入：coords（数组）：目标坐标
  • 输入：speed（整数）：运动速度
  • 返回：运动确认

末端执行器控制

• control_gripper - 控制夹爪开合
• control_pump - 控制吸泵开关

系统命令

• go_zero - 回零位
• emergency_stop - 紧急停止

高级运动控制

• execute_action_sequence - 执行自定义动作序列
  • 输入：sequence_name（字符串）：动作序列的描述性名称
  • 输入：actions（数组）：动作列表，每个动作包含：
    • type：动作类型（"angles"、"coords"、"gripper"、"pump"、"wait"）
    • angles/coords：目标位置（根据类型）
    • speed：移动速度（可选，默认50）
    • duration：动作持续时间（秒，可选）
    • gripper_action："open"或"close"（夹爪类型）
    • pump_action："on"或"off"（吸泵类型）
  • 输入：default_interval（浮点数）：动作间默认间隔（可选，默认0.5秒）
  • 返回：执行状态及完成的动作数
  • 注意：此工具可实现逗猫、画圆、跳舞等复杂行为，通过动作序列组合实现各种创意动作

资源（Resources）

• status://current - 实时机器人状态信息

提示（Prompts）

• robot_control_guide - 机器人控制交互指南

  • 参数：task（任务类型）
  • 提供分步骤操作指导

• design_action_sequence - 设计自定义动作序列的模板

  • 参数：
    • task_description：任务描述（如"跳舞"、"逗猫"、"按摩"等）
  • 提供结构化的动作序列设计指导
  • 帮助设计流畅连续的动作及合理的时间安排

快速开始

安装配置

1. 确保已安装 Python 3.10
2. 安装依赖：
   bash

   pip install robotarm-mcp-p340
   

Cursor 配置方法

有三种方法在 Cursor 中配置 MCP：

方法 1：Python 模块配置（推荐用于已安装的包）

如果您已通过 pip 安装了包：
python

{
  "mcpServers": {
    "mycobot": {
      "command": "填写安装了robotarm-mcp-p340的虚拟环境文件夹下的python路径",
      "args": ["-u", "-m", "mycobot_mcp"],
      "env": {
        "SIMULATE": "1"
      }
    }
  }
}

示例如下：

{
  "mcpServers": {
    "mycobot": {
      "command": "D:\\anaconda3\\envs\\test-robotarm\\python.exe",
      "args": ["-u", "-m", "mycobot_mcp"],
      "env": {
        "SIMULATE": "1"
      }
    }
  }
}

方法 2：开发配置（用于从 GitHub 克隆的项目）

如果您从 GitHub 克隆并正在开发：
python

{
  "mcpServers": {
    "mycobot": {
      "command": "填写安装了该项目虚拟环境文件夹下的python路径",
      "args": [
        "-u",
        "-m",
        "mycobot_mcp"
      ],
      "env": {
        "SIMULATE": "1",
        "PYTHONPATH": "填写 src 文件夹的绝对路径"
      },
      "cwd": "填写项目根目录的绝对路径"
    }
  }
}

示例如下：

{
  "mcpServers": {
    "mycobot": {
      "command": "D:\\Anaconda3\\envs\\mycobot-mcp\\python.exe",
      "args": [
        "-u",
        "-m",
        "mycobot_mcp"
      ],
      "env": {
        "SIMULATE": "1",
        "PYTHONPATH": "D:\\AI\\mycobot-mcp\\src"
      },
      "cwd": "D:\\AI\\mycobot-mcp"
    }
  }
}

重要说明：

• "SIMULATE": "1"为无硬件设备的模拟测试，实机测试需要把SIMULATE值设置为"0"
• 方法二需要在项目虚拟环境中安装requirements.txt中的项目依赖
• 必须使用 -u 参数禁用 Python 输出缓冲
• 设置 PYTHONPATH 包含 src 目录
• 根据您的安装路径调整路径

方法 3：批处理文件配置（Windows）

1. 创建批处理文件 start_mcp_server.bat：
   batch

   @echo off
   cd /d D:\AI\mycobot-mcp
   set PYTHONPATH=D:\AI\mycobot-mcp\src
   set SIMULATE=1
   D:\Anaconda3\envs\mycobot-mcp\python.exe -u -m mycobot_mcp
   

2. 配置 Cursor：
   batch

   {
     "mcpServers": {
       "mycobot": {
         "command": "D:\\AI\\mycobot-mcp\\start_mcp_server.bat"
       }
     }
   }
   

配置步骤

1. 打开 Cursor 设置（Ctrl+,）
2. 搜索 "MCP" 或 "Model Context Protocol"
3. 使用上述方法之一添加配置
4. 重启 Cursor 使配置生效

验证配置

配置成功后，您应该看到：

• ✅ MCP 状态显示 "9 tools enabled"
• ✅ 聊天中可用工具：connect_robot、get_robot_status 等

使用示例

1. 连接机器人：

   • "连接我的 ultraArm P340 机械臂"
   • "初始化 COM3 端口的机器人"（根据您设备的实际 COM 端口调整数字，默认是 3）

2. 基础运动：

   • "移动机械臂到位置 [200, 0, 150]"
   • "设置关节角度为 [45, 30, -20]"
   • "回到零位"

3. 夹爪控制：

   • "打开夹爪"
   • "闭合夹爪抓取物体"
   • "开启吸泵"

4. 复杂任务：

   • "用机械臂逗猫"
   • "在桌上画个圆"
   • "演示如何写汉字"
   • "让机器人跟着音乐跳舞"
   • "创建一个自定义的挥手动作序列"

开发模式

设置 SIMULATE=1 无需硬件测试：
bash

export SIMULATE=1  # Linux/Mac
set SIMULATE=1     # Windows

故障排除

如果工具加载失败：

1. 检查 Cursor 的 MCP 日志：
   • 视图 → 输出 → 选择 "MCP" 通道
   • 查看错误信息2. 本地测试服务器：

   # 对于已安装的包
   python -m mycobot_mcp
   
   # 对于开发模式（从项目根目录）
   cd D:\AI\mycobot-mcp
   set PYTHONPATH=src
   python -m mycobot_mcp
   

2. 常见问题和解决方案：

   • "No module named 'mycobot_mcp'"：

     • 开发模式：确保 PYTHONPATH 包含 src 文件夹
     • 已安装：从项目根目录运行 pip install -e .

   • "工具未加载"：

     • 检查是否使用 -m mycobot_mcp 而不是 -m mycobot_mcp.server
     • 验证开发模式下 cwd 设置为项目根目录

   • 配置提示：

     • ✅ 始终使用 -u 标志实现无缓冲输出
     • ✅ 设置 PYTHONPATH 为 src 文件夹（而不是 src/mycobot_mcp）
     • ✅ 使用 cwd 为开发设置工作目录
     • ❌ 不要再直接运行 server.py

安全指南

⚠️ 重要安全信息：

1. 确保机器人周围有足够空间
2. 运动时远离机械部件
3. 出现异常立即使用紧急停止
4. 测试新动作时使用低速
5. 按摩演示仅用于展示，勿用于真人
6. 与宠物互动时全程监督

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。