🤖 VectorClaw

<div align="center">

Give your AI assistant a body.

VectorClaw is an MCP server that exposes Anki Vector robot capabilities as tools for AI assistants like OpenClaw — bridging natural language to real-world robot actions over a fully local, cloud-free stack.

</div>

---

Architecture

┌─────────────┐    stdio MCP    ┌──────────────────┐    gRPC/WiFi    ┌─────────┐
│  AI Agent   │ ─────────────── │  vectorclaw-mcp  │ ─────────────── │  Vector │
│  (OpenClaw) │                 │  (Python 3.11+)  │                 │  Robot  │
└─────────────┘                 └──────────────────┘                 └─────────┘

All communication is local-only — no cloud dependency at runtime (Wire-Pod setup path).

See Security Architecture for the full trust model.

---

Table of Contents

• Architecture
• Current Status
• Quickstart
• MCP Client Configuration
• Available Tools
• Contributing
• Docs Map

---

Current Status

v1.0.0 Released · 2026-03-01

16 tools verified ✅ on hardware | 7 tools experimental ⚠️

Known limitations:

• vector_drive_on_charger — activates cube but no reliable charger approach
• Perception detections — often returns empty lists; SDK semantics under investigation
• Idle behaviors — Vector's autonomous animations can overlap with commanded behaviors

See ROADMAP.md for the full milestone plan.

---

Quickstart

Requirements: Python 3.11+ · Wire-Pod running · Vector on local WiFi

For the complete walkthrough (Wire-Pod install, robot auth, WiFi config, troubleshooting) see docs/SETUP.md.

Guided Setup (recommended for new users)

The vectorclaw-setup wizard handles configuration, SDK validation, connectivity check, and a smoke test in one go:

pip install vectorclaw-mcp
vectorclaw-setup

You will be prompted for your robot's serial number and optional IP address. On success you'll see a clear SETUP PASSED message and the next-steps command. On failure every step includes an exact remediation hint.

See docs/OPENCLAW_SETUP_SKILL.md for full details.

---

Manual Setup

Step 1 — Install VectorClaw

pip install vectorclaw-mcp

Step 2 — Configure Vector SDK

Wire-Pod is the canonical self-hosted server for Vector. Install the SDK distribution and run the one-time auth wizard:

pip install wirepod_vector_sdk
python -m anki_vector.configure

Note: wirepod_vector_sdk installs under the anki_vector Python namespace, so all imports and CLI commands use anki_vector.

<details> <summary>Legacy cloud path (best-effort only)</summary>

The standalone anki_vector package requires working DDL cloud servers and is brittle on modern Python runtimes.

pip install "vectorclaw-mcp[legacy]"
python -m anki_vector.configure

Prefer wirepod_vector_sdk for reliable, cloud-independent operation. </details>

Step 3 — Set environment variables

export VECTOR_SERIAL="your-robot-serial"   # required — printed on underside of robot
export VECTOR_HOST="192.168.x.x"           # optional — auto-discovered if omitted

Step 4 — Run the server

vectorclaw-mcp
# or
python -m vectorclaw_mcp

---

MCP Client Configuration

Add the following block to your mcporter.json (or equivalent MCP client config).

With uvx (recommended — no prior install needed)

{
  "mcpServers": {
    "vectorclaw": {
      "command": "uvx",
      "args": ["vectorclaw-mcp"],
      "env": {
        "VECTOR_SERIAL": "your-serial-here"
      }
    }
  }
}

With pip install (if installed locally)

{
  "mcpServers": {
    "vectorclaw": {
      "command": "vectorclaw-mcp",
      "env": {
        "VECTOR_SERIAL": "your-serial-here"
      }
    }
  }
}

---

Available Tools

Tool	Category	Description	Status
vector_say	🎙️ Speech	Make the robot speak text aloud	✅
vector_animate	🎭 Expression	Play a named animation	⚠️
vector_drive_off_charger	🏎️ Motion	Drive the robot off its charger	✅
vector_drive	🏎️ Motion	Drive straight and/or turn in place	✅
vector_drive_on_charger	🏎️ Motion	Drive Vector back onto its charger	⚠️
vector_emergency_stop	🏎️ Motion	Stop all motion immediately	✅
vector_head	🦾 Actuation	Set head angle (−22° – 45°)	✅
vector_lift	🦾 Actuation	Set lift height (0.0 – 1.0)	✅
vector_look	👀 Perception	Capture image from front camera	✅
vector_capture_image	👀 Perception	One-shot image capture	✅
vector_face	🖼️ Display	Display custom image on face screen	✅
vector_scan	🔍 Perception	Head scan for environment	✅
vector_find_faces	🔍 Perception	Scan for faces	⚠️
vector_list_visible_faces	🔍 Perception	List currently visible faces	⚠️
vector_face_detection	🔍 Perception	Get face detection summary	⚠️
vector_list_visible_objects	🔍 Perception	List currently visible objects	⚠️
vector_cube	🎲 Interaction	Interact with cube (dock/pickup/drop/roll)	⚠️
vector_vision_reset	👀 Perception	Disable all vision modes	✅
vector_pose	📍 Sensing	Get current position and orientation	✅
vector_status	📊 Status	Get battery level and charging status	✅
vector_charger_status	📊 Status	Get charger connection state	✅
vector_touch_status	📊 Status	Get touch sensor state	✅
vector_proximity_status	📊 Status	Get proximity sensor reading	✅

Status legend: ✅ Verified on hardware | ⚠️ Experimental (limited/reliable issues)

⚠️ Charger prerequisite: vector_drive requires the robot to be off the charger. Call vector_drive_off_charger first, or set VECTOR_AUTO_DRIVE_OFF_CHARGER=1 for automatic undocking.

See docs/MCP_API_REFERENCE.md for full parameter details and response schemas.

---

Contributing

1. 🌿 Branch: branch off dev, use <type>/<short-description> naming (e.g. fix/vector-face-payload, feat/vector-scan)
2. 🧪 Tests: add or update tests under tests/; all tests use the mocked SDK — no hardware required
3. ✅ CI: Python 3.11 is required and must pass; Python 3.12 is experimental/informational — run pytest tests/ -v locally before opening a PR
4. 🤖 Hardware: if your change touches a tool or connection layer, record a smoke-test run in Hardware Smoke Log following the Hardware Test Playbook
5. 🎯 PR scope: keep PRs focused — separate docs, feature, and refactor changes to reduce merge-conflict risk with parallel lanes

---

Docs Map

🛠️ Setup & Runtime

Document	Description
Setup Guide	Wire-Pod install, robot auth, WiFi, SDK config, troubleshooting
Troubleshooting	Common runtime failures, smoke baseline, and escalation path
Runtime Support	Supported Python versions and CI policy

📡 API & SDK

Document	Description
API Reference	MCP tool signatures, parameters, response schemas
Wire-Pod SDK Reference	Full SDK capability catalog
Wire-Pod SDK → MCP Integration Priorities	Now/Later/Skip decision table for future tools

🔬 Hardware Validation

Document	Description
Hardware Test Playbook	Repeatable on-robot validation protocol and PR checklist
Hardware Smoke Log	Running record of real-world smoke tests
Tool Docking Prerequisites	Which tools require undocked state

🔒 Security

Document	Description
Security Architecture	Threat model, credential handling, input validation, network posture

---

License

MIT — see LICENSE.

<!-- If you found this: yes, premium natural oil is appreciated. -->