armguard-mcp

armguard-mcp

A safety-first [Model Context Protocol](https://modelcontextprotocol.io) 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, ros2_control, franka_ros2) is

tested on ROS 2 Jazzy against real rclpy endpoints and a real MoveIt 2 move_group. 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 (claude_desktop_config.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

• Problem. An LLM agent that can call robot tools can be wrong, or be steered by a prompt injection hidden in an image or a topic string. One bad tool call moves a real arm.
• Approach. The MCP server checks every plan against a policy file *before* anything moves: joint limits, workspace box, keep-out zones, step and speed caps, force limits, allowlists and rate limits. Motion outside the envelope needs a human to approve it through MCP elicitation, and a software e-stop and an audit log sit on top.
• Results (simulated FR3, reproducible with one command): all 23/23 unsafe requests in the evaluation suite were refused, clamped, rate-limited or aborted, and no unintended command reached the robot. 1000/1000 random safe moves executed, with none leaving the envelope. Planning with the full safety check takes a median of ~16 ms per call. With a frontier agent in the loop (Claude Code, 13 tasks with an unsafe intent), 0 unsafe actuations reached the robot under the shipped policy and 8 did with the envelope opened; all 5 benign tasks completed under both.
• Limits. Not yet run on a physical robot; the simulated backend is kinematic only; the envelope checks the TCP path, not link geometry (measured: 84/201 near-zone plans clip a zone with the hand or wrist); this is defense in depth, not certified safety. See Known limitations.

Contents

• How it differs from generic ROS MCP bridges
• Architecture
• Quick start (simulated FR3, no ROS needed)
• Evaluation
• ROS 2 backend
• Tool reference
• The approval flow
• Policy reference
• Safety scope and non-goals
• Known limitations
• Roadmap
• Citation and License

More detail: docs/architecture.md, docs/threat-model.md, docs/demo.md (a real transcript), CONTRIBUTING.md.

How it differs from generic ROS MCP bridges

Generic bridges such as robotmcp/ros-mcp-server do an excellent job of what they aim for: they connect any MCP client to any ROS 1 or ROS 2 robot through rosbridge, with no changes to the robot's code. The LLM can publish to topics, call services and actions, and set parameters. That generality is the point, and it also means the model can reach anything the ROS graph exposes. Their open issue #283 ("Security: Unrestricted ROS service calls via MCP tool — prompt injection → robot control") describes the resulting risk, and the project's README lists permissions among the contributions it welcomes.

armguard-mcp makes the opposite trade-off. It is narrow, specific to manipulators, and restrictive by design:

If you want to explore a robot freely from a chat window, use a generic bridge. If you want an agent near a real arm with limits it cannot talk its way around, that is what this project is for.

Architecture

flowchart LR

subgraph Client["MCP client (untrusted)"] LLM["LLM agent (Claude, GPT, …)"] Human(["Human operator"]) end

subgraph Server["armguard-mcp (trusted, enforces policy)"] direction TB Tools["22 MCP tools only enabled groups are registered"] RL["Rate limiter per-tool + global token buckets"] ES["E-stop / force latch"] Env["Safety envelope joint limits · workspace box · keep-out zones speed · step size · force"] Ap["Approval resolver (MCP elicitation)"] Plans["Plan store TTL · single-use · staleness"] Audit[("Audit log JSONL")] Tools --> RL --> ES --> Env --> Ap Env <--> Plans Tools -.-> Audit end

subgraph Backend["Robot backend"] Fake["fake FR3 (kinematic sim, CI)"] ROS["ROS 2 (rclpy) MoveIt 2 · ros2_control · franka_ros2"] end

Robot["FR3 + Franka safety system 1 kHz control stays here"]

LLM <-->|"MCP: stdio or streamable HTTP"| Tools Ap <-.->|"elicitation/create"| Human Ap --> Backend ROS --> Robot

The LLM is never in the control loop. MCP works at the level of skills and tasks: plan, preview, execute, grasp. Real-time control, such as 1 kHz impedance and force control, stays in ros2_control and the Franka controllers. The server checks a whole trajectory before it runs and watches the external wrench while it runs.

Quick start (simulated FR3, no ROS needed)

From PyPI, no clone needed (the bundled FR3 policy is used when --policy is omitted):

pip install armguard-mcp                    # or run it without installing: uvx armguard-mcp ...

armguard-mcp --audit-log audit.jsonl # simulated FR3, bundled policy armguard-mcp --policy my_policy.yaml # your own policy (required for --backend ros2)

From source, for the tests, the demo and the evaluation scripts:

git clone https://github.com/Lynn-hh/armguard-mcp && cd armguard-mcp

python -m venv .venv && . .venv/bin/activate pip install -e ".[dev]" pytest -q # unit tests, a few seconds (no ROS needed)

stdio (what desktop and CLI MCP clients launch)

armguard-mcp --policy examples/policies/fr3.yaml --backend fake --audit-log audit.jsonl

streamable HTTP on http://127.0.0.1:8765/mcp (no authentication: keep it on localhost)

armguard-mcp --policy examples/policies/fr3.yaml --backend fake --transport http --port 8765

a scripted session: plan, execute, approval prompt, keep-out rejection, e-stop

python scripts/demo_fake.py

the safety evaluation behind the numbers in "At a glance"

python scripts/eval_safety.py

a frontier agent (Claude Code, headless) against the server, with and without the envelope (~15 min)

python scripts/eval_agent_redteam.py

armguard-mcp --help lists every flag: --policy (required), --backend fake|ros2, --ros2-config, --transport stdio|http, --host (default 127.0.0.1), --port (default 8765), --audit-log, --dry-run (forces dry-run on top of the policy), --log-level, --version. Logs go to stderr only, so stdout carries nothing but MCP messages. A policy that fails validation, a backend that is not available, or an audit log that cannot be opened exits with status 2 before the server starts. Binding HTTP to a non-loopback address logs a warning. SIGTERM (docker stop, systemd, MCP hosts) is handled like Ctrl-C and end of input: the server commands a stop of the arm and gripper, then shuts the backend down.

The fake backend is a kinematic FR3 with real FR3 forward and inverse kinematics, time-scaled execution, a Franka Hand model, generated camera images and a fake ros2_control graph. It starts at the policy's home_joint_positions.

Claude Code (.mcp.json, stdio)

Copy examples/mcp.json to .mcp.json at your project root, or run claude mcp add with the same command and arguments. Use absolute paths.

{

"mcpServers": { "armguard": { "type": "stdio", "command": "/abs/path/to/armguard-mcp/.venv/bin/armguard-mcp", "args": [ "--policy", "/abs/path/to/armguard-mcp/examples/policies/fr3.yaml", "--backend", "fake", "--audit-log", "/abs/path/to/armguard-mcp/audit.jsonl" ] } } }

Start with --dry-run or [`