Mc3000 MCP Server

mc3000-mcp

Safe local MCP control for SKYRC MC3000-compatible chargers.

mc3000-mcp connects an AI agent to a battery charger without handing it an unsupervised hardware API. BLE control is local. Charging is dry-run by default. Live writes and starts need explicit per-slot confirmation. Emergency stop is always one call away.

Agent  ──MCP stdio──  mc3000-mcp  ──BLE FFE0/FFE1──  SKYRC MC3000
                          │
                          ├─ profile validation and chemistry limits
                          ├─ dry-run profile rendering
                          ├─ confirmation tokens for live writes/starts
                          └─ bounded, redacted audit log

Hardware warning. Wrong chemistry, current, voltage, slot, or unsupervised charging can damage cells or start a fire. The MCP server is the safety boundary, not the LLM. Keep the charger in sight. See SECURITY.md.

Install

# crates.io
cargo install mc3000-mcp --locked

# Arch Linux
paru -S mc3000-mcp

# released tag, if you prefer installing from source
cargo install --git https://github.com/nietonchique/mc3000-mcp.git --tag v0.2.4 --locked

A Linux x86_64 MCPB bundle is attached to each release for MCPB-compatible clients.

Linux BLE requires BlueZ/D-Bus:

bluetoothctl show
# If the adapter is off:
sudo rfkill unblock bluetooth && bluetoothctl power on

Connect an MCP client

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

Client-specific examples are in examples/.

Try it without hardware:

{
  "mcpServers": {
    "mc3000": {
      "command": "mc3000-mcp",
      "args": ["--backend", "fake"]
    }
  }
}

Agent skill

charger-agent uses the portable Agent Skills layout: one folder with a SKILL.md manifest. No vendor-specific installer is required.

Install it for Codex:

mkdir -p ~/.codex/skills
curl -fsSL https://github.com/nietonchique/mc3000-mcp/releases/download/v0.2.4/mc3000-mcp-skill-v0.2.4.tar.gz \
  | tar -xz -C ~/.codex/skills

For OMP, use ~/.omp/agent/skills as the destination. For Claude-compatible clients, use ~/.claude/skills. Hermes can also install the raw file, but it is just one compatible client—not the distribution format.

The folder contains the charger workflow plus a pre-start checklist and example profile. It is guidance only; the Rust MCP server remains the enforced safety boundary.

CLI

The default command starts MCP stdio. Read-only diagnostics are also available directly:

mc3000-mcp --version
mc3000-mcp scan --timeout 8
mc3000-mcp status --address AA:BB:CC:DD:EE:FF
mc3000-mcp --backend fake scan

The CLI can scan and read slots. It cannot write profiles, change settings, or start charging.

Safe workflow

1. Read slot status.
2. Validate a battery profile.
3. Render it as a dry run.
4. Apply it with confirmation_token=APPLY_PROFILE_SLOT_<slot>.
5. Start it with a separate confirmation_token=START_SLOT_<slot>.
6. Monitor voltage, current, temperature, and status.
7. Use charger.stop_slot / charger.stop_all immediately if anything looks wrong.

Example dry run for physical slot 4 / API slot 3:

{
  "name": "charger.apply_profile",
  "arguments": {
    "slot": 3,
    "profile_id": "nimh-aa-conservative-charge"
  }
}

Start requires a second explicit confirmation:

{
  "name": "charger.start",
  "arguments": {
    "slot": 3,
    "confirmation_token": "START_SLOT_3"
  }
}

Emergency stop is deliberately tokenless:

{"name": "charger.stop_all", "arguments": {}}

Tools

Production surface is namespaced as charger.*:

Fourteen legacy mc3000_* tools remain for protocol/debugging work. They use the same confirmation policy for non-emergency writes. Raw writes cannot implicitly start slots and always block factory/calibration restore opcodes.

Safety model

• API slots are zero-based 0..3; physical slots are 1..4.
• apply_profile defaults to dry_run=true.
• Live profile writes require exactly APPLY_PROFILE_SLOT_<slot>.
• Starts require exactly START_SLOT_<slot>.
• Safety checks run before any backend call; unsupported chemistry fails closed.
• NiMH/Eneloop/NiCd, LiIon, and LiFe have enforced limits.
• Unknown charger models and MC5000 connections are read-only.
• Session logs redact addresses and confirmation tokens and are bounded in memory.

Full model: docs/safety-model.md. Profile schema and bundled examples: docs/profile-schema.md.

Compatibility

Confirmed live: SKYRC MC3000 firmware 1.23, hardware 2.20.

Protocol details are documented from the official Android app and hardware testing in docs/ble-protocol-notes.md and docs/reverse-notes.md. MC5000 support is intentionally read-only until writes are verified on real hardware.

Charger firmware behavior can differ. A profile write acknowledgement is not proof that the charger applied it—start the slot and verify mode/current/status.

Development

cargo fmt --all -- --check
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo test --all-features --locked
cargo audit && cargo deny check

The fake backend keeps hardware out of normal tests and CI. See CONTRIBUTING.md for the full workflow and hardware-safety rule.

Documentation

• Security and disclosure: SECURITY.md
• Safety model: docs/safety-model.md
• Supported devices: docs/supported-devices.md
• Examples: docs/examples.md
• Release/publishing checklist: docs/publishing.md
• Agent skill: skill/SKILL.md

License

Apache-2.0. See LICENSE.