VectorClaw

🤖 VectorClaw

[](https://github.com/danmartinez78/VectorClaw/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](https://pypi.org/project/vectorclaw-mcp/) [](LICENSE) [](ROADMAP.md)

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.

---

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](docs/SECURITY_ARCHITECTURE.md) for the full trust model.

---

Table of Contents

• [Architecture](#architecture)
• [Current Status](#current-status)
• [Quickstart](#quickstart)
• [MCP Client Configuration](#mcp-client-configuration)
• [Available Tools](#available-tools)
• [Contributing](#contributing)
• [Docs Map](#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](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](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/OPENCLAWSETUPSKILL.md](docs/OPENCLAWSETUPSKILL.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.

Legacy cloud path (best-effort only)

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.

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/MCPAPIREFERENCE.md](docs/MCPAPIREFERENCE.md) for full parameter details and response schemas.

---

Contributing

1. 🌿 Branch: branch off dev, use / 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](docs/HARDWARESMOKELOG.md) following the [Hardware Test Playbook](docs/HARDWARETESTPLAYBOOK.md)
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](docs/SETUP.md) | Wire-Pod install, robot auth, WiFi, SDK config, troubleshooting | | [Troubleshooting](docs/TROUBLESHOOTING.md) | Common runtime failures, smoke baseline, and escalation path | | [Runtime Support](docs/RUNTIME_SUPPORT.md) | Supported Python versions and CI policy |

📡 API & SDK

| Document | Description | |----------|-------------| | [API Reference](docs/MCPAPIREFERENCE.md) | MCP tool signatures, parameters, response schemas | | [Wire-Pod SDK Reference](docs/VECTORSDKREFERENCE.md) | Full SDK capability catalog | | [Wire-Pod SDK → MCP Integration Priorities](docs/WIREPODSDKMCPINTEGRATIONPRIORITIES.md) | Now/Later/Skip decision table for future tools |

🔬 Hardware Validation

| Document | Description | |----------|-------------| | [Hardware Test Playbook](docs/HARDWARETESTPLAYBOOK.md) | Repeatable on-robot validation protocol and PR checklist | | [Hardware Smoke Log](docs/HARDWARESMOKELOG.md) | Running record of real-world smoke tests | | [Tool Docking Prerequisites](docs/TOOLDOCKINGPREREQUISITES.md) | Which tools require undocked state |

🔒 Security

| Document | Description | |----------|-------------| | [Security Architecture](docs/SECURITY_ARCHITECTURE.md) | Threat model, credential handling, input validation, network posture |

---

License

MIT — see [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: danmartinez78
• Source: danmartinez78/VectorClaw
• License: MIT

Install and usage instructions live in the source repository linked above.