Skip to main content
Glama

xusbcan-cli

面向 AI Agent 的 CAN 总线调试工具。

中文 | English

免责声明:本项目与广州致远电子股份有限公司(周立功/ZLG)及其产品没有任何关联、赞助、背书或利益关系。"周立功"、"ZLG"、"zlgcan" 等名称均为其各自权利人的商标。本项目是独立的第三方工具,仅通过公开的二次开发接口对接其硬件;驱动与 SDK 版权归其权利人所有,由用户从官方渠道获取。

以后端服务形态运行,同时提供标准 CLI 与 MCP(Model Context Protocol)接口,让 AI Agent 能直接完成 CAN 报文的收发、监听、周期发送等调试操作——无需人工操作上位机软件,即可实现 Agent 自动化联合调试。

目标与展望

在 AI 时代,让 Agent 能像使用普通工具一样操作 CAN 总线:结构化输出、稳定契约、可被程序化调用。

我们希望 xusbcan-cli 成为 AI 与车载 / 工业 CAN 总线之间的标准桥梁,让「用 Agent 自动完成整条总线的联调、诊断、验证」成为常态。

Related MCP server: MCP-Edge

特性

  • 统一设备抽象:多家厂商 CAN 卡(周立功 / Vector / PEAK / 创芯 …)通过统一接口接入,Agent 看到的是同一套命令语义

  • CLI 与 MCP 共享核心:行为一致,结构化 JSON / JSONL 输出,Agent 无需解析人类可读日志

  • 轻量:核心运行时依赖仅 python-can

安装

从 PyPI 安装(推荐)

pip install xusbcan-cli        # 仅 CLI + 核心
pip install xusbcan-cli[mcp]   # 追加 MCP 服务器支持

从源码安装

git clone https://github.com/Archaofan/xusbcan-cli.git
cd xusbcan-cli
pip install -e .          # 仅 CLI + 核心
pip install -e ".[mcp]"   # 追加 MCP 服务器支持

快速开始

1. 准备环境

运行前提:

  • Python 3.11+(64 位)

  • 一张周立功 USBCAN-2E-U 卡

  • 周立功 USB 设备驱动(让系统识别设备)

  • 周立功二次开发 SDK 资料包(提供 zlgcan.dll)

获取 SDK:从周立功官方资料页下载二次开发 SDK 资料包:

https://manual.zlg.cn/web/#/152?page_id=5332

下载后解压即符合要求——官方资料包解压出的 SDK 目录已包含运行所需的 zlgcan.dll 与 kerneldlls/(内核 DLL),无需额外整理。

配置环境变量:将解压后的 SDK 目录路径设为环境变量 ZLG_SDK_DIR:

# Windows(PowerShell,用户级持久化)
[Environment]::SetEnvironmentVariable("ZLG_SDK_DIR", "D:\path\to\解压后的SDK目录", "User")

# 或临时设置(仅当前终端生效)
set ZLG_SDK_DIR=D:\path\to\解压后的SDK目录

指向的目录结构应为:

<ZLG_SDK_DIR>/
├── zlgcan.dll      # 核心库(必需)
└── kerneldlls/     # 内核 DLL 目录(必需,与 zlgcan.dll 同目录)

2. 编写配置 xusbcan.toml

[[devices]]
name = "ecu"          # 逻辑别名,Agent 通过它引用设备
vendor = "zlg"
model = "USBCAN-2E-U"
channel = 1
nominal = 250000      # 波特率

3. 使用 CLI

xusbcan list                                # 列出设备
xusbcan send ecu --id 0x123 --data "01 02 03"   # 发送
xusbcan receive ecu --timeout 1             # 接收一帧
xusbcan monitor ecu --duration 5            # 监听
xusbcan status ecu                          # 状态

4. 启动 MCP 服务器

xusbcan-mcp

默认走 stdio。若配置里把传输设为 http,服务只绑定 127.0.0.1。

在你的 MCP 客户端(Claude Desktop / Cursor / Claude Code 等)里注册它。配置示例:

{
  "mcpServers": {
    "xusbcan": {
      "command": "xusbcan-mcp",
      "env": {
        "ZLG_SDK_DIR": "D:\\path\\to\\zlgcan_x64",
        "XUSBCAN_CONFIG": "D:\\path\\to\\xusbcan.toml"
      }
    }
  }
}

连接后,Agent 即可通过 send_frame、receive_frame、monitor、periodic_start 等工具直接调试 CAN 总线。

面向 Agent 的 Skill

本仓库附带可安装的 Agent Skill(skills/xusbcan),说明如何调用 CLI / MCP、如何写可独立运行的收发脚本,以及常见失败时该怎么处理。任意兼容 Agent Skills 的客户端都可以安装,不限于某一种编辑器:

npx skills add Archaofan/xusbcan-cli --skill xusbcan

在项目目录中执行即可装到当前工程;加 -g 则装到用户目录。需要指定客户端时加上 -a(例如 claude-code、cursor)。

支持的硬件

当前已验证:周立功 USBCAN-2E-U。

项目基于 python-can,天然覆盖大量厂商后端(Vector、PEAK、socketcan、slcan、Kvaser …)。新增一种 CAN 卡,通常只需增加一个后端适配或一条设备配置,即可让 Agent 用同一套接口操作它。

欢迎适配更多 CAN 卡 🙌

如果你手头有其它型号的 CAN 卡(Vector / PEAK / 创芯 / Kvaser / 国产卡 …),欢迎贡献后端适配或设备配置。让更多硬件能被 AI Agent 直接使用,是这个项目的核心目标之一。

参与

  • 报告问题、提出需求、提交 PR

  • 贡献新的 CAN 卡适配

  • 一起把「Agent 自动化联合调试 CAN」这件事做成通用能力

License

本项目采用 MIT License。第三方组件的许可条款见 third_party/NOTICES。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Serial communication and protocol analysis MCP server that gives AI coding assistants direct access to serial ports for reading, writing, decoding, and capturing embedded device output.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Raspberry Pi peripheral bus access, enabling AI agents to interact with CAN, I2C, SPI, UART, and GPIO directly through natural language.
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Agentic Hardware-in-the-Loop (Agentic HIL) lets coding agents develop firmware on real embedded boards: flash, reset, read UART and exchange CAN traffic, diagnose and fix. Local, policy-gated MCP tools support OpenOCD, pyOCD and STM32CubeProgrammer, with pytest for CI.
      44
      2,327 PyPI
      26
      Apache 2.0