armguard-mcp server

armguard-mcp

<!-- mcp-name: io.github.Lynn-hh/armguard-mcp -->

A safety-first Model Context Protocol server for ROS 2 manipulators. It lets an LLM agent inspect a robot arm, plan motions, preview them and execute them. Every action passes through a safety envelope that the server enforces outside the model: joint limits, a workspace box and keep-out zones, speed and step-size caps, force/torque thresholds, allowlists, rate limits, a software e-stop, human approval through MCP elicitation, and an audit log. A prompt, or a prompt injection hidden in a camera image or topic string, can change what the model asks for. It cannot change what the server allows.

Status: alpha. The policy engine, safety envelope, approval flow, audit log and all 22 MCP tools run

against a simulated Franka FR3 backend. The ROS 2 backend (MoveIt 2, ros2control, frankaros2) is

tested on ROS 2 Jazzy against real rclpy endpoints and a real MoveIt 2 movegroup. It has not**

been run on a physical robot yet.

This is defense in depth, NOT certified functional safety. See

Safety scope and non-goals.

Real output of scripts/demo_fake.py against the simulated FR3, abridged (full transcript).

Try it in 60 seconds

No ROS, no clone. The package ships the FR3 demo policy, so the simulated arm starts with one command:

uvx armguard-mcp            # or: pip install armguard-mcp && armguard-mcp

Point your MCP client at it and ask it to move the arm. Claude Desktop (claudedesktopconfig.json) and Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "armguard": { "command": "uvx", "args": ["armguard-mcp"] }
  }
}

Claude Code:

claude mcp add armguard -- uvx armguard-mcp

Then try, in order: "Where is the arm?", "Move the gripper 10 cm up" (runs), "Rotate joint 1 by 50 degrees" (asks you to approve), "Move to x=0.62, y=0.42, z=0.30" (refused: that is inside the camera_mount keep-out zone). Every decision lands in the audit log; --audit-log audit.jsonl keeps it. The bundled policy is for the simulated robot only: --backend ros2 always requires your own --policy.

At a glance

Shortened. The full README is on GitHub.