Physical MCP

AI代理和真实机器人之间的安全层。

](https://www.npmjs.com/package/@ricardothe3rd/physical-mcp)       

快速开始 · 为什么选择物理MCP？ · 安全层 · 全部100个工具 · 建筑

______________________________________________________________________

\[！警告\] 物理MCP控制 真实硬件。在部署到物理机器人之前，始终从保守的安全限制开始，并在模拟中进行彻底测试。

这是什么？

将任何AI代理（Claude、GPT、Gemini、本地LLM）连接到任何内置ROS2机器人 速度限制, 地理围栏边界, 紧急停止, 速率限制, 安全开关，以及 完整审计日志记录每一条命令都经过安全检查 之前 它会到达你的机器人。

npx @ricardothe3rd/physical-mcp

就是这样，一个命令。100个MCP工具。您的机器人不会收到任何不安全的命令。

它看起来像什么

You: "Move the robot forward slowly"
Claude → ros2_topic_publish(topic=/cmd_vel, msg={linear: {x: 0.15}})
 ✅ Safety check PASSED → Published to /cmd_vel

You: "Go full speed, 10 m/s!"
Claude → ros2_topic_publish(topic=/cmd_vel, msg={linear: {x: 10.0}})
 🛑 BLOCKED: Linear velocity 10.00 m/s exceeds limit of 0.5 m/s
    → Command never reaches the robot. Logged to audit trail.

You: "Emergency stop!"
Claude → safety_emergency_stop(reason="Manual activation")
 🔴 E-STOP ACTIVE → Zero velocity sent. All commands blocked.
    → Release requires explicit "CONFIRM_RELEASE" string.

每个命令（允许或阻止）都会记录在审计跟踪中，并带有时间戳、违规和完整上下文。

为什么选择物理MCP？

现有的MCP-to-ROS2网桥允许AI代理向机器人发送原始命令 零护栏这对模拟来说很好，但对真实硬件来说很危险。

Physical MCP强制执行安全层 之前 任何命令都会到达您的机器人：

：火箭：快速启动

1.启动模拟+桥接

cd docker
docker compose up

这将启动一个 凉亭模拟 在端口9090上安装TurtleBot3和ROS2网桥。

2.将Physical MCP添加到Claude

claude mcp add physical-mcp -- npx @ricardothe3rd/physical-mcp

3.与你的机器人对话

问克劳德这样的问题：

• *“列出所有ROS2主题”*
• *“机器人目前的姿势是什么？”*
• *“以0.1 m/s的速度向前移动机器人”*
• *“显示安全状态”*
• *“激活紧急停止”*

\[！提示\] 对于Claude Desktop，将PhysicalMCP添加到您的 claude_desktop_config.json: ``json { "mcpServers": { "physical-mcp": { "command": "npx", "args": ["@ricardothe3rd/physical-mcp"], "env": { "PHYSICAL_MCP_BRIDGE_URL": "ws://localhost:9090", "PHYSICAL_MCP_POLICY": "/path/to/my-policy.yaml" } } } } ``

：building_construction：建筑

┌──────────────┐              ┌────────────────────────────────────────┐
│   AI Agent   │◄────────────►│       MCP Server (TypeScript)          │
│  (Claude,    │  MCP         │                                        │
│  GPT, etc.)  │  protocol    │  ┌──────────────────────────────────┐  │
└──────────────┘              │  │        ⛨  Safety Layer           │  │
                              │  │                                  │  │
                              │  │   ┌──────────┐  ┌────────────┐   │  │
                              │  │   │ Velocity │  │  Geofence  │   │  │
                              │  │   │  Limits  │  │ Boundaries │   │  │
                              │  │   └──────────┘  └────────────┘   │  │
                              │  │   ┌──────────┐  ┌────────────┐   │  │
                              │  │   │   Rate   │  │  E-Stop +  │   │  │
                              │  │   │  Limiter │  │ Audit Log  │   │  │
                              │  │   └──────────┘  └────────────┘   │  │
                              │  │                                  │  │
                              │  └──────────────────────────────────┘  │
                              └───────────────────┬────────────────────┘
                                                  │
                                         WebSocket (port 9090)
                                                  │
                              ┌───────────────────▼────────────────────┐
                              │        ROS2 Bridge (Python)            │
                              │  rclpy + websockets                    │
                              │  Secondary e-stop as fail-safe         │
                              └───────────────────┬────────────────────┘
                                                  │
                                             ROS2 DDS
                                                  │
                              ┌───────────────────▼────────────────────┐
                              │           ROS2 Robot                   │
                              │  Topics, Services, Actions             │
                              └────────────────────────────────────────┘

安全层位于TypeScript MCP服务器中，用于评估 每 发布、服务调用和行动目标。Python桥有一个辅助紧急停止，作为额外的故障保护。

：shield：安全层

每个可能移动或影响机器人的命令都会通过策略引擎。以下是所有可用的安全机制：

双层紧急停止

最关键的安全功能。两个独立的层确保机器人停止：

1. 主要（TypeScript）： 在MCP服务器级别阻止所有发布/服务/操作命令
2. 中学（Python）： 桥梁级紧急停止向以下设备发布零速度 /cmd_vel 并取消所有活动目标

释放需要显式字符串 CONFIRM_RELEASE 以防止意外恢复。

速度限制

限制任何物体的线速度和角速度 geometry_msgs/msg/Twist 消息：

velocity:
  linearMax: 0.5   # m/s (default)
  angularMax: 1.5  # rad/s (default)

超过限制的命令是 阻塞 并记录。（可选）启用 箝位模式 在保持方向不变的情况下，将速度缩小到最大值：

velocity:
  linearMax: 0.22
  clampMode: true   # reduce to max instead of blocking

每个主题的速度限制

不同机器人或关节的不同速度限制：

topicVelocityOverrides:
  - topic: /arm/cmd_vel
    linearMax: 0.1        # Arm moves slowly
    angularMax: 0.5
  - topic: /base/cmd_vel
    linearMax: 1.0        # Base can go faster

加速度限制

通过限制速度变化的速度来防止剧烈运动：

acceleration:
  enabled: true
  linearMaxAccel: 1.0    # m/s²
  angularMaxAccel: 3.0   # rad/s²

土工围栏边界

定义机器人必须停留的工作空间：

geofence:
  xMin: -5.0
  xMax: 5.0
  yMin: -5.0
  yMax: 5.0
  zMin: 0.0
  zMax: 2.0

添加 接近警告 在到达边界之前：

geofenceWarningMargin: 1.0  # warn within 1m of boundary

速率限制

防止ROS2图被淹没：

rateLimits:
  publishHz: 10          # max publishes per second
  servicePerMinute: 60   # max service calls per minute
  actionPerMinute: 30    # max action goals per minute

被屏蔽的主题和服务

防止访问敏感的系统资源：

blockedTopics:
  - /rosout
  - /parameter_events

blockedServices:
  - /kill
  - /shutdown

Deadman开关

如果在超时时间内没有收到心跳，自动激活紧急停止：

deadmanSwitch:
  enabled: true
  timeoutMs: 30000   # 30 seconds

呼叫 safety_heartbeat 定期地。如果AI代理断开连接，deadman开关会自动停止机器人。

指挥批准（循环中的人）

执行危险命令前需要明确的人工批准：

commandApproval:
  enabled: true
  requireApprovalFor:
    - ros2_topic_publish
    - ros2_action_send_goal
  pendingTimeout: 30000   # 30s before approval expires

安全评分

跟踪AI代理会话的“安全”程度：

• 分数： 0–100（100=允许所有命令，0=全部阻止）
• 阻塞率： 被阻止的命令百分比
• 违规类型： 问题所在的细分
• 会话持续时间： 会话运行了多长时间

核对 safety_status.

审计日志

每个命令都记录了时间戳、唯一ID、命令类型、目标、安全检查结果（允许/阻止）、违规详细信息和执行结果。查询方式 safety_audit_log 或导出为JSON safety_export_audit_log.

：扳手：MCP工具（100）

25个类别的100个工具。每个发布、服务调用和操作目标都通过安全层。

核心ROS2工具

Topic Tools (5) — publish, subscribe, echo messages

Service Tools (3) — call ROS2 services

Action Tools (4) — send goals, cancel, track status

System & Parameter Tools (7) — nodes, params, health

安全工具（21）

Full safety tool list — e-stop, geofence, audit, approval, policies

机器人感知与传感

Camera Tools (3) — image topics, camera info, previews

Sensor Tools (2) — IMU, lidar, sensor summaries

TF Tools (2) — coordinate transforms

导航与规划

Path Tools (4) — path planning, navigation status

Map Tools (3) — occupancy grids, costmaps

Waypoint Tools (4) — save, navigate, manage waypoints

车队和设备管理

Fleet Tools (3) — multi-robot management

Launch Tools (3) — start/stop ROS2 launch files

Namespace Tools (3) — ROS2 namespace management

高性能

Batch & Conditional Tools (3) — execute multiple commands, conditions

Scheduled Tools (3) — cron-like command scheduling

Recording Tools (3) — record and replay topic data

History Tools (3) — command history and replay

Introspection Tools (3) — message/service/action type info

Diagnostic & Network Tools (5) — system diagnostics, network monitoring

Power & Description Tools (4) — battery, URDF, joint info

：齿轮：配置

环境变量

安全政策

创建一个YAML文件并指向它 PHYSICAL_MCP_POLICY:

name: my-robot
description: Custom policy for my robot

velocity:
  linearMax: 0.3
  angularMax: 1.0

geofence:
  xMin: -2.0
  xMax: 2.0
  yMin: -2.0
  yMax: 2.0
  zMin: 0.0
  zMax: 1.0

rateLimits:
  publishHz: 5
  servicePerMinute: 30
  actionPerMinute: 15

blockedTopics:
  - /rosout
  - /parameter_events

blockedServices:
  - /kill
  - /shutdown

支持部分策略——您省略的任何字段都将恢复为默认值。

包括两个内置策略：

• default.yaml --任何ROS2机器人的保守限制
• turtlebot3.yaml --针对凉亭中的TurtleBot3汉堡进行了调整（0.22 m/s线性，2.84 rad/s角速度）

：dart:Tech Stack

：open_file_folder：项目结构

Click to expand full tree

physical-mcp/
├── packages/
│   ├── mcp-server/              # TypeScript MCP server (npm package)
│   │   ├── src/
│   │   │   ├── index.ts         # Entry point — 100 tool registrations
│   │   │   ├── bridge/          # WebSocket client, connection manager, heartbeat
│   │   │   ├── tools/           # 25 tool category files (100 tools total)
│   │   │   ├── safety/          # Policy engine, geofence, rate limiter, audit, collision
│   │   │   ├── types/           # ROS2 type definitions
│   │   │   └── utils/           # Logger, health checks, input validation, profiles
│   │   └── policies/            # YAML safety policy files
│   └── ros2-bridge/             # Python ROS2 bridge (rclpy + websockets)
│       └── physical_mcp_bridge/
│           ├── bridge_node.py   # Main ROS2 node + WebSocket server
│           ├── ws_manager.py    # WebSocket manager with backpressure
│           ├── protocol.py      # Shared protocol (mirrors TS)
│           ├── discovery.py     # ROS2 graph discovery
│           ├── topic_handler.py # Topic pub/sub/echo
│           ├── service_handler.py
│           ├── action_handler.py
│           ├── telemetry.py     # Bridge health metrics
│           └── msg_validator.py # Message type validation
├── docker/
│   ├── docker-compose.yml       # Full stack (sim + bridge)
│   ├── Dockerfile.bridge        # ROS2 Humble + bridge
│   └── Dockerfile.sim           # Gazebo + TurtleBot3
├── resources/
│   └── docs/                    # Guides, tutorials, API reference
└── README.md

：锤子与扳手：开发

建筑

# TypeScript MCP server
cd packages/mcp-server
npm install
npm run build

# Python bridge (in ROS2 environment)
cd packages/ros2-bridge
pip install -e .

本地运行

# Terminal 1: Start the bridge (requires ROS2)
physical-mcp-bridge

# Terminal 2: Start the MCP server
cd packages/mcp-server
npm run dev

测试

cd packages/mcp-server
npm test

码头工人

# Build and start everything
cd docker
docker compose up --build

# The bridge runs on port 9090
# Gazebo sim launches with TurtleBot3 Burger

：package：要求

：问题：常见问题

How is this different from robotmcp?

robotmcp和其他MCP-ROS2网桥将命令直接传递给机器人，无需进行安全检查。PhysicalMCP添加了一个完整的安全层（速度限制、地理围栏、速率限制、紧急停止、审计日志），在每个命令到达机器人之前对其进行评估。看 对比表.

Does this work with local LLMs?

对。PhysicalMCP是一个MCP服务器，因此它可以与任何兼容MCP的客户端（Claude、GPT或通过MCP客户端运行的本地模型）配合使用。无论哪个AI发送命令，安全层都是相同的。

Can I use this with real hardware (not just simulation)?

对。MCP服务器通过Python桥连接到任何ROS2系统。启动机器人（或具有ROS2访问权限的机器）上的桥，指向 PHYSICAL_MCP_BRIDGE_URL 在它，它工作。 从保守的安全限制开始 并在使用真实硬件之前进行彻底测试。

What happens if the WebSocket connection drops?

连接管理器每5秒自动尝试重新连接一次。如果桥断了，断路器可以防止洪水泛滥。断开连接时发送的命令返回一个明确的错误。桥侧紧急停止功能保持独立运行。

Can I have different safety policies for different robots?

对。集 PHYSICAL_MCP_POLICY 指向具有机器人特定限制的YAML文件。包含两个内置策略（默认+TurtleBot3）。您还可以在运行时通过以下方式更新限制 safety_update_velocity_limits 和 safety_update_geofence 工具。

Is the safety layer bypassable?

不通过MCP接口。所有发布、服务和操作命令都通过TypeScript服务器中的策略引擎。Python桥有一个辅助紧急停止，作为额外的故障安全机制。没有“跳过安全”标志。

：rotating_light：故障排除

Bridge not connected

Bridge not connected. Start the ROS2 bridge and try again.
Expected bridge at: ws://localhost:9090

确保Python桥正在运行。如果使用Docker： cd docker && docker compose up。如果在本地运行： physical-mcp-bridge。检查端口9090是否未被防火墙阻止。

tsc build hangs

如果 npm run build 挂起，确保您使用的工具文件版本与 toInputSchema() 辅助功能。这 zodToJsonSchema 返回类型导致TypeScript类型推断在直接转换为时循环 Tool['inputSchema'].

Docker Gazebo display issues

如果Gazebo在macOS/Linux上没有显示窗口，则需要X11转发：

# macOS: install XQuartz, then:
xhost +local:docker

# Linux:
xhost +local:root

对于无头模式，设置 GAZEBO_HEADLESS=1.

ROS2 topics not showing up

如果 ros2_topic_list 如果返回空值，则桥可能在模拟之前已经启动。在模拟完全加载后重新启动网桥：

docker compose restart bridge

Safety violations blocking commands unexpectedly

通过询问来检查哪个策略处于活动状态 *“显示安全状态”*。看看速度限制和地理围栏边界。如果它们过于严格，请在运行时更新它们(*“将线速度限制更新为1.0 m/s”*)或者创建自定义的YAML策略文件。

WebSocket connection drops

1. 检查MCP服务器和网桥之间的网络稳定性
2. 检查网桥进程是否仍在运行： docker compose ps
3. 如果启用了安全开关，请确保 safety_heartbeat 正在被召唤 timeoutMs
4. 连接管理器每5秒用断路器重试一次——一旦桥接器恢复，错误就会解决

E-Stop won't release

紧急停止发布需要明确确认：通过 confirm: true 随着 CONFIRM_RELEASE。如果网桥级别的紧急停止处于活动状态，请重新启动网桥容器。检查原始触发器的审核日志： safety_audit_log.

Node.js version incompatibility

PhysicalMCP使用需要Node.js 18+的现代JavaScript功能（可选链接、顶级等待、ES模块）。核对 node --version 并使用升级 非易失性存储器 如果需要的话。

Permission denied on Linux

不要像根一样跑桥。将您的用户添加到 docker 组：

sudo usermod -aG docker $USER
newgrp docker

：握手：贡献

欢迎投稿！看 贡献.md 用于开发设置和指南。

特别需要帮助的领域：

• 特定机器人平台（UR5、Spot、Franka、无人机）的安全政策
• 额外的传感器/摄像头集成
• 文档改进和教程
• 来自真实硬件部署的Bug报告

：page_facing_up：许可证

分布在 MIT许可证。参见 LICENSE 了解详情。

MIT License

Copyright (c) 2026 Ricardothe3rd

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

______________________________________________________________________

物理MCP 是机器人行业所需的安全层。

如果这个项目对你有用，请考虑给它一颗星。

建造于 里卡多·阿加纳 与克劳德