mcpField
C
Coppeliaslim Test

Coppeliaslim Test

本地服务
github.com/alsak0de开发工具474 周前更新
代码仓库

关于 Coppeliaslim Test

面向机器人仿真开发与测试的 CoppeliaSim MCP 服务，提供关节控制和场景描述工具，并支持 FastAPI 或 FastMCP 后端及 HTTP/SSE、stdio 传输。

主要功能

  1. 01按指定角度旋转关节
  2. 02列出关节类型和限位
  3. 03描述机器人与场景对象
  4. 04支持 HTTP/SSE 和 stdio 传输

适用场景

  1. 01在仿真中控制机器人关节
  2. 02向 LLM 提供机器人和场景信息

MCP 相关

向 MCP 客户端提供关节控制及机器人、场景描述工具，支持 HTTP/SSE 和 stdio 连接。

#coppeliaslim#mcp-server#robotics-simulation

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "CoppeliaSlim-mcpserver": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote"
      ]
    }
  }
}
启动命令npx -y mcp-remote

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npmmcp-remote

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

CoppeliaSim MCP 服务

一个基于 Python 的 MCP（运动控制协议）服务实现，用于 CoppeliaSim 机器人仿真，支持 FastAPI 和 FastMCP 后端。

功能

  • JSON-RPC 2.0 协议
  • 关节控制以及机器人／场景描述工具
  • 支持 HTTP/SSE 和 stdio 传输
  • 灵活、适合大模型使用的输出

要求

  • Python 3.x
  • CoppeliaSim（原名 V-REP），版本 4.3 或更高版本（需要 ZeroMQ 远程 API）
  • 必需的 Python 软件包（参见 requirements.txt）

安装

0.（推荐）创建 Conda 环境

强烈建议使用 Conda 环境，以避免依赖冲突：

conda create -n coppelia-mcp python=3.10
conda activate coppelia-mcp

然后即可继续执行以下步骤。

1. 克隆仓库并安装依赖
git clone https://github.com/alsak0de/CoppeliaSlim-mcpserver.git
cd CoppeliaSlim-mcpserver
pip install -r requirements.txt

使用方法

1. 启动 CoppeliaSim 并加载机器人模型
2. 运行 MCP 服务

注意：MCP 服务通常使用 stdio 传输，前提是工具提供方与 MCP 服务运行在同一台机器上，而且 MCP 主机和客户端通常也运行在同一台机器上。 本项目实现了 SSE 传输，可支持完整的分布式部署，让 CoppeliaSim、MCP 服务和 MCP 客户端运行在不同机器上。

应该使用哪个服务？
  • **选项 A（基于 FastAPI，coppelia_mcp.py）**推荐用于大多数生产部署，尤其适合需要标准 Web 服务功能、与 Web 工具集成或自定义端点的场景。
  • **选项 B（基于 FastMCP，coppelia_fastmcp.py）**适用于 Agent／大模型原生工作流、stdio 传输，或纯 MCP／Agent 集成。
  • **选项 C（直接运行脚本，coppelia_mcp.py）**适用于开发、调试，或需要通过 CLI 指定 --coppeliaHost 的场景。
选项 A：基于 FastAPI 的服务（coppelia_mcp.py）[推荐用于生产环境]
COPPELIASIM_HOST=<coppelia_host> uvicorn coppelia_mcp:app --host 0.0.0.0 --port 8000
  • 这是在生产环境中运行 FastAPI 应用的标准方式。
  • 使用 COPPELIASIM_HOST 环境变量设置 CoppeliaSim 主机。
  • 优先级：
    1. COPPELIASIM_HOST 环境变量（如果已设置）
    2. 默认值：127.0.0.1
  • 传输方式：
    • HTTP POST（JSON-RPC）
    • /sse 端点上的 SSE
    • Stdio（通过 npx mcp-remote 桥接，见下文）
选项 B：基于 FastMCP 的服务（coppelia_fastmcp.py）
  • 默认方式： 
    python coppelia_fastmcp.py --host 0.0.0.0 --port 8000 --coppeliaHost <coppelia_host>
    • 可通过 --coppeliaHost 指定 CoppeliaSim 主机（默认值：127.0.0.1）。
  • 传输方式：
    • HTTP POST（JSON-RPC）
    • /sse 端点上的 SSE
    • Stdio（原生支持，或在需要时通过 npx mcp-remote 实现）
选项 C：直接运行脚本（开发／调试，coppelia_mcp.py）
python coppelia_mcp.py --host 0.0.0.0 --port 8000 --coppeliaHost <coppelia_host>
  • 在开发、调试，或需要通过 CLI 指定 --coppeliaHost 时使用此方法。
  • 不建议用于生产环境；部署时优先使用选项 A。
3. 连接客户端
  • SSE/HTTP：
    • SSE 客户端使用 /sse 端点（推荐用于现代大模型／Agent 客户端）
    • 示例：http://localhost:8000/sse
  • Stdio：
    • 如果客户端仅支持 stdio，请使用桥接程序： 
      npx mcp-remote http://localhost:8000
    • 或者，如果 FastMCP 原生支持 stdio 传输，请将客户端配置为使用该传输方式
4. 自动批准工具调用
  • 在大多数客户端（例如 Cursor）中，在服务设置里启用“自动批准”，以免每次调用工具时都需要确认。

API 工具

  • rotate_joint：将关节旋转到指定角度
  • list_joints：列出所有关节及其类型和限位
  • describe_robot：返回所有机器人元素的详细说明，便于大模型使用
  • describe_scene：返回所有场景对象的说明（不包括机器人关节）

注意： 所有工具逻辑现已集中在 tools.py 中。要添加新工具，请在 tools.py 中定义函数（将 sim 作为第一个参数），然后根据需要在 coppelia_mcp.py 和 coppelia_fastmcp.py 中注册。这样可确保两个服务共享相同的工具逻辑并保持一致。

说明

  • 两个服务的默认地址均为 0.0.0.0:8000，但你可以通过 --host 和 --port 覆盖。
  • 为了与现代大模型／Agent 客户端获得最佳兼容性，请使用 SSE 端点。
  • 对于仅支持 stdio 的客户端，请使用 npx 桥接工具或 FastMCP 的原生 stdio 支持。
  • 为什么／何时使用 uvicorn？
    • 对于基于 FastAPI 的服务（coppelia_mcp.py），你需要 uvicorn（或其他 ASGI 服务）来实际提供 HTTP/SSE 端点，因为 FastAPI 只是一个框架，本身不包含 Web 服务。
    • 对于基于 FastMCP 的服务（coppelia_fastmcp.py），只有在需要提供 HTTP/SSE 端点时才需要 uvicorn。如果你以 stdio 模式运行 FastMCP（用于 Agent／命令行集成），则不需要 uvicorn 或任何 Web 服务，因为所有通信都通过 stdin/stdout 进行。

作者与致谢

由 Albert Sagarra 创建并维护。
欢迎并鼓励社区贡献。有关如何参与的详情，请参阅 CONTRIBUTING.md。

许可证

本项目采用 MIT License 许可。
你可以根据该许可证的条款自由使用、修改和分发本项目。

使用 Docker 运行

这是确保部署或测试环境干净、隔离的推荐方式。

1. 构建 Docker 镜像
docker build -t coppelia-mcp .
2. 运行 MCP 服务容器

重要：

  • 你必须使用 --coppeliaHost 参数指定 CoppeliaSim 主机，以便 MCP 服务连接到容器外运行的 CoppeliaSim 实例。
  • 服务始终在容器内绑定到 0.0.0.0。
  • 端口可以作为 docker run 的第一个参数设置（默认值：8000）。你必须公开服务端口，才能从容器外访问 API。
  • 使用 --rm 标志可在容器停止时自动移除容器（无需持久化）。
示例（将 <coppelia_host> 替换为你的 CoppeliaSim 主机 IP）：
docker run --rm -p 8000:8000 coppelia-mcp --coppeliaHost <coppelia_host>
  • 若要使用其他端口，请将其作为第一个参数传入并映射该端口：
docker run --rm -p 9000:9000 coppelia-mcp 9000 --coppeliaHost <coppelia_host>
  • 端口之后的任何其他参数都会直接传递给服务脚本。
  • 如果 CoppeliaSim 在同一台机器上运行（但不在 Docker 中），请使用 --coppeliaHost host.docker.internal（在 Mac／Windows 上），或使用主机的 IP 地址（在 Linux 上）。
  • 如果 CoppeliaSim 在另一个容器中运行，请确保两个容器位于同一个 Docker 网络，并使用相应的服务／容器名称或 IP。
3. 访问服务
  • MCP 服务可通过 http://localhost:8000（或你映射的端口）访问。
  • SSE 客户端请使用 /sse 端点；也可以向 / 发送 POST 请求以使用 JSON-RPC。
故障排除
  • 无法连接到 CoppeliaSim：
    • 确保 --coppeliaHost 的值正确，且从容器内可以访问。
    • 检查防火墙和网络设置。
  • 端口已被占用：
    • 更改 -p 标志中的主机端口（例如，-p 8080:8000）。
  • 持久化数据：
    • 此配置不会持久化任何数据。如果需要持久保存日志或配置，请挂载卷。

如需高级用法（例如 FastMCP 服务、自定义端口或卷），请根据需要调整 Docker 命令和参数。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。