Skip to main content
Glama
Sign In
embedded-mcp-toolkit

embedded-mcp-toolkit

by smk-h
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

一、 简介

1. 是什么

embedded-mcp-toolkit 是一个基于 MCP（Model Context Protocol）协议的嵌入式板卡远程管理工具，通过多个 MCP 工具提供嵌入式设备交互能力。支持以下功能：

  • 串口管理：打开/关闭串口连接、发送命令、读取输出、一键登录（自动检测 PSH 并解锁）、进入 U-Boot 命令行、U-Boot 会话标记管理、经 ZMODEM 上传/下载文件、单片机（MCU）裸固件交互

  • SSH 管理：打开/关闭 SSH 会话、发送命令、读取输出、一键登录（自动检测 PSH 并解锁）、查看远端设备活跃连接、远程编译（结构化错误/警告反馈）、经 SFTP 上传/下载文件

  • ADB 管理：一次性 adb 命令（adb install / adb push 等）、交互式 ADB shell 会话、设备列表扫描

  • 本地 PowerShell：一次性执行本地 PowerShell 命令（独立进程、UTF-8 编码、超时强杀进程树，命令与结果随业务日志体系落盘到 .embedded/log/local/YYYY-MM-DD）

  • Windows 系统扫描：扫描可用 COM/LPT 端口、扫描本机网络适配器与 IP 配置、目标 IP 子网可达性分析

  • 基础信息：查询 MCP 服务器版本、获取设备配置信息（单台或全部）、跨连接类型查询活跃会话元数据、查询 MCP 宿主端点

  • 多会话管理：同时保持多个串口、SSH、ADB 会话，支持独立读写

  • KeyProvider 密钥管理：支持文件 IPC 和终端交互两种方式，自动处理 PSH 动态口令生成的密钥

  • 进程退出自动清理：客户端断开或进程终止时自动释放所有串口、SSH、ADB 连接

项目背景与价值定位（为什么需要它、与 PowerShell 直调的能力分界与场景选型）详见 项目简介。

2. 架构关系

OpenCode、MCP Client 与 MCP Server 的三层关系如下：

┌─────────────────────────────────────────────┐
│  OpenCode (MCP Host)                        │
│  ┌────────────┐  ┌────────────┐             │
│  │ MCP Client │  │ MCP Client │  ...        │
│  │ (stdio)    │  │ (http)     │             │
│  └─────┬──────┘  └─────┬──────┘             │
└────────┼───────────────┼────────────────────┘
         │               │
    stdin/stdout      HTTP/SSE
         │               │
┌────────┴────────┐   ┌──┴───────────┐
│ MCP Server A    │   │ MCP Server B │
│ (embedded-mcp-  │   │ (其他服务)    │
│  toolkit)       │   │              │
└─────────────────┘   └──────────────┘

角色

说明

在本项目中的体现

MCP Host

AI 应用，管理多个 Client，把 tool result 喂给 LLM

OpenCode / Claude Code

MCP Client

Host 内部组件，与 Server 保持 1:1 连接，通过 JSON-RPC 通信

Host 每配置一个 Server 就创建一个 Client

MCP Server

提供 tools 供 Agent 调用的独立进程

embedded-mcp-toolkit

通信流程：OpenCode 读取配置 → 创建 MCP Client → 以 stdio 启动 MCP Server 子进程 → 双方通过 JSON-RPC 通信。Agent 说"调用 xx 工具"时，Host 通过 Client 向 Server 发 tools/call，结果返回给 LLM。

注意：Server 发送的推送通知（如 notifications/message）由 Client 接收后止于 Host，不会转发给 Agent。因此需要 Agent 感知的事件应通过 tool 返回值（pull 模式）传递。

Related MCP server: Hyper MCP Terminal

二、 快速开始

1. npm 安装

目前支持工具的全局安装和本地指定目录安装，但是全局安装后还是只能在某个目录配置使用（需要 claude 配置文件、设备配置文件、mcp 配置文件以及日志等），暂未测试过全局配置。

mkdir mcp-toolkit
cd mcp-toolkit

# 当前目录安装
npm i @smai-kit/embedded-mcp-toolkit

# 初始化
./node_modules/.bin/embedded-mcp-toolkit init

安装配置完成后目录结构如下：

mcp-toolkit
├── .claude                      # claude配置目录
│   ├── CLAUDE.md
│   ├── settings.local.json      # 项目配置文件（自动生成，一般无需改）
│   ├── skills                   # claude skills,只是写了一些技能，实际可能不需要
│   ├── start-claude.bat.tmp     # 以指定环境变量启动claude的bat脚本
│   └── start-claude.ps1.tmp     # 以指定环境变量启动claude的powershell脚本
├── .mcp.json                    # claude code的mcp配置文件
├── .opencode                    # opencode 的配置目录（非 Claude 用户可忽略）
│   └── opencode.json
├── .embedded                    # 嵌入式工具包专属目录（配置 + 日志统一收纳）
│   ├── configs                  # 配置目录
│   │   ├── challenge.txt        # 登录psh时的挑战码（动态口令）
│   │   ├── config.example.yaml  # 配置模板文件（含完整字段说明，供参考）
│   │   ├── config.yaml          # 实际生效的配置（随包发布，只含 default，按需编辑）
│   │   ├── devices              # 设备配置分文件目录，一台设备一个 .yaml
│   │   │   └── board-example.yaml # 示例设备配置（复制并改名为你的设备）
│   │   └── password_input.txt   # 密钥文件，通过挑战码生成
│   └── log                      # 日志目录，按天分子目录（业务日志 + 各设备会话日志）
│       └── 2026-05-27            # 当天日期子目录
│           └── 2026-05-27_09-06-09.log
├── node_modules                 # node 依赖包目录（npm 自动生成）
│   ├── .bin
│   ├── .package-lock.json
│   ├── @smai-kit                # @smai-kit/embedded-mcp-toolkit中是编译后的js脚本
│   ├── #...
│   └── zod
├── package-lock.json
└── package.json                 # npm 项目依赖清单

各配置文件（.claude/settings.local.json、.mcp.json 环境变量、设备配置、日志参数）的逐项说明见 配置指南。

2. 源码安装

git clone 源码后：

npm i         # 安装依赖
npm run build # 编译，编译后就可以在当前目录下启动claude使用了

3. 启动与验证

cd mcp-toolkit
claude

然后在 claude 中执行 /mcp list 查看 MCP 服务是否连接：

  Manage MCP servers
  1 server

    Project MCPs (D:\Temp\aaa\.mcp.json)
  ❯ embedded-board · ✔ connected · 44 tools

embedded-board 前面的 ✔ connected 即表示连接成功。

4. 常用提示词

# 获取当前设备信息
❯ 当前设备信息是什么

# 列出/查看会话（跨串口、SSH、ADB）
❯ 当前有哪些会话

# 登录设备，没有xxx的话是会用默认设备
❯ ssh一键登录xxx设备
❯ 串口一键登录xxx设备

# 退出登录
❯ 关闭ssh_id
❯ 关闭串口serial_id
❯ 关闭所有会话

全部工具的用途与对应提示词见 工具参考。

三、 文档导航

1. 使用指南

文档

内容

配置指南

客户端接入配置（.mcp.json / settings.local.json）、默认设备优先级、设备配置两种布局、split 命令、常用字段、日志与数据目录

工具参考

基础 / 串口 / ADB / SSH / Windows 全量工具表、工具注册策略、单片机（MCU）模式

常见问题

串口被拒绝、环境变量未生效、重启被中断

2. 设计与部署

文档

内容

项目简介

项目背景、与 PowerShell 直调的能力分界、场景选型

MCP 工具超时机制

客户端（协议层）：请求 60s 超时的成因、opencode / Claude Code 的 timeout 配置

exec 超时机制

服务端（工具内部）：常驻命令识别、采样超时与兜底超时、timeoutMs 传参约定、全局默认值

串口 ZMODEM 文件传输

ZMODEM 传输原理、持续输出对传输的影响、参数与重试

U-Boot 正则配置指南

serial.uboot 提示符识别的正则适配

DTR/RTS 线序与 STM32 ISP 模式

单片机线序诊断、进 ISP 与救砖

Linux 远程连接 Windows MCP

跨机部署的 SSH 桥接配置

本地 MCP 配置

local-mcp-config 在其它项目目录复用本 MCP

exe 打包指南

单文件 exe 打包与分发

上表前两篇同叫"超时"，但层级不同：LV025 管「客户端等多久就判失败」（tools/call 往返时长，由 MCP Client 决定）；LV095 管「服务端何时认为一条命令跑完了」（提示符检测 + 常驻命令采样/兜底超时，由工具内部决定）。排查"请求超时"看前者，排查"命令被提前中断/迟迟不返回"看后者。

完整文档列表见 docs/ 目录：01-MCP设计（机制与设计分析）、02-部署与远程（跨机部署方案）、03-使用指南（配置、工具与排错）。

Available Tools

38 tools
adb_device_listA

List all connected ADB devices and their status (device, offline, unauthorized, etc.)

Inputs: no named parameters.

adb_execA

Execute a one-shot ADB command without a persistent session. Use for adb devices, install, push, or short shell commands.

Inputs: command (required), device.

adb_shell_closeA

Close an ADB shell session and terminate the adb process.

Inputs: session_id (required).

adb_shell_execA

Send a command to an ADB shell session and wait for the output. Combines write + read in one call, with automatic completion detection (marker/prompt). IMPORTANT: Do NOT issue concurrent commands to the same session_id — the ADB shell is a single channel; concurrent calls will interleave output and corrupt results. Always wait for the previous command to finish before sending the next one. If you need parallel execution, open multiple sessions via adb_shell_open.

Inputs: command (required), session_id (required), clear, timeoutMs.

adb_shell_openA

Open an interactive ADB shell session to an Android device. Returns the initial banner output.

Inputs: device.

adb_shell_readA

Read output from an ADB shell session. Do NOT call this concurrently with adb_shell_exec/adb_shell_write on the same session_id — concurrent access to the same ADB shell corrupts the output buffer.

Inputs: session_id (required), clear.

adb_shell_send_ctrlA

Send a control character (Ctrl+C/U/D/Z) to an ADB shell session without appending a newline.

Inputs: key (required), session_id (required).

adb_shell_writeA

Send a command to an ADB shell session. Do NOT call this concurrently with adb_shell_exec/adb_shell_read on the same session_id — concurrent access to the same ADB shell corrupts the output buffer.

Inputs: command (required), session_id (required), clear.

device_info_toolA

Get device configuration. Uses the default device when no name is given; returns all devices when 'all' is specified.

Inputs: device.

greet_toolB

Greet someone by name

Inputs: name (required).

host_infoA

Query the MCP host endpoint (username@ip) of @smai-kit/embedded-mcp-toolkit for constructing cross-machine file transfers (scp) when this MCP (@smai-kit/embedded-mcp-toolkit) runs on Windows and the AI client runs on Linux. Also returns the @smai-kit/embedded-mcp-toolkit log save directories (business log & raw data log absolute paths) for locating/cleaning up logs. Returns 'local started' with no endpoint for local launches.

Inputs: no named parameters.

network_scan_toolA

Scan Windows network adapters and configurations (IP, MAC, status, speed)

Inputs: no named parameters.

port_scan_toolA

Scan Windows Device Manager for available COM (serial) and LPT (parallel) ports

Inputs: no named parameters.

serial_closeA

Close a serial port session and release the port.

Inputs: session_id (required).

serial_downloadA

Download a binary file from the device over ZMODEM via an existing serial session. The device must have lrzsz installed (sz command). IMPORTANT: this tool triggers the device-side sz by itself (via send_cmd); do NOT manually run sz (or serial_exec/write sz) on the session beforehand — a pre-started sz enters its own sending state that breaks the tool's ZMODEM handshake. Just call this tool and pass send_cmd when a directory change is needed (e.g. "cd /home && sz {remote}"). remote_path resolves on the device relative to the shell's current working directory — prefer an absolute path, or combine send_cmd with a cd to pin the directory. If the remote file does not exist or is unreadable, sz errors out and the transfer fails (a partial local file, if any, is removed on failure). Blocks until transfer completes, fails, or times out; progress is logged to stderr. Two timeouts: idle_timeout aborts on stalled transfer (real failure); timeout caps total duration and reports a suggested value if still progressing.

Inputs: local_path (required), session_id (required), remote_path (required), timeout, +2 more.

serial_enter_ubootA

Enter U-Boot by rebooting the device and stopping autoboot. Detection rules (autoboot prompts, command prompt, verify env keys) are configurable via device config serial.uboot; built-in defaults already cover Hit/Press x any-key/key/SPACE/Ctrl+C/Ctrl+u x stop/interrupt/abort wordings. Pre-check before rebooting (buffer tail, zero side effects): already at a U-Boot prompt returns success without rebooting; at a login/Password prompt fails fast ('reboot' would be consumed as input). restart=true forces a reboot cycle even when already at a U-Boot prompt: sends the U-Boot 'reset' command and re-intercepts autoboot to land back in U-Boot (Linux is never involved; the Linux-side path keeps using 'reboot'). Kernel-boot detection and prompt matching are not gated on an interrupt: devices that boot straight to the kernel fail fast, devices that disable autoboot (bootdelay=-2) succeed fast, instead of waiting out the full timeout. After the interrupt, two-layer strategy: prompt match first; if not matched within a short window, sends 'printenv' and verifies U-Boot env keys. Fails fast on kernel boot or verify timeout.

Inputs: session_id (required), restart, timeoutMs.

serial_execA

Send a command to a serial shell session and wait for the output. Combines write + read in one call, with automatic completion detection (marker/prompt). IMPORTANT: Do NOT issue concurrent commands to the same session_id — the serial console is a single channel; concurrent calls will interleave output and corrupt results. Always wait for the previous command to finish before sending the next one. If you need parallel execution, open multiple sessions via serial_open.

Inputs: command (required), session_id (required), clear, timeoutMs.

serial_openB

Open a serial port connection and start an interactive shell session. Returns the initial banner output.

Inputs: port, device, parity, baudRate, +2 more.

serial_readA

Read output from a serial shell session. Do NOT call this concurrently with serial_exec/serial_write on the same session_id — concurrent access to the same serial console corrupts the output buffer.

Inputs: session_id (required), clear.

serial_send_ctrlA

Send a control character (Ctrl+C/U/D/Z) to a serial shell session without appending a newline.

Inputs: key (required), session_id (required).

serial_shell_loginA

One-click serial login: connect, detect PSH state, auto-unlock if locked, and return a ready session. Combines open + PSH detect + unlock into a single call.

Inputs: key, device, timeout.

serial_uboot_stateA

Query, detect, or force-set the U-Boot mark of a serial session. The mark decides serial_exec's marker wrapping (U-Boot sessions use plain style without subshell). Actions: 'detect' (default) — classify the live environment in two layers. Passive first (zero side effects): buffer-tail anchors only — U-Boot prompt, login prompt, kernel boot, autoboot countdown. Anything else (e.g. a bare '#' tail, ambiguous between Linux root shell and custom U-Boot prompts) falls through to an active two-step probe: 'printenv' (>=2 U-Boot env verify keys → U-Boot), then 'echo $$' (whole-line numeric PID → system; whole-line '$$' or 'Unknown command' → U-Boot). Conclusive results sync the mark automatically. WARNING: each probe consumes one line of input — do NOT detect while a command may still be running or waiting for interactive input (e.g. Y/N). 'set'/'clear' — force the mark when auto-detection is out of sync; 'status' — read the mark only, no device I/O.

Inputs: session_id (required), action.

serial_uploadA

Upload a binary file to the device over ZMODEM via an existing serial session. The device must have lrzsz installed (rz command). IMPORTANT: this tool triggers the device-side rz by itself (via recv_cmd); do NOT manually run rz (or serial_exec/write rz) on the session beforehand — a pre-started rz enters its own waiting state that breaks the tool's ZMODEM handshake. Just call this tool and pass recv_cmd when a working directory change is needed (e.g. "cd /home && rz"). Blocks until transfer completes, fails, or times out; progress is logged to stderr. Two timeouts: idle_timeout aborts on stalled transfer (real failure); timeout caps total duration and reports a suggested value if still progressing.

Inputs: local_path (required), session_id (required), timeout, recv_cmd, +2 more.

serial_writeB

Send a command to a serial shell session. Do NOT call this concurrently with serial_exec/serial_read on the same session_id — concurrent access to the same serial console corrupts the output buffer.

Inputs: command (required), session_id (required), clear.

session_infoA

Query active session metadata. Pass session_id for one session, device for all sessions of a device, or neither for all active sessions. Each session returns: session id, connection type (serial/ssh/adb), device name, connection info (e.g. COM3@115200), creation time, and the raw session log file path (serial/ssh/adb traffic recorded continuously by the server, including full boot logs after reset/reboot).

Inputs: device, session_id.

ssh_buildA

Execute a build command on the remote server via SSH, wait for completion, classify errors/warnings, and return structured build results for AI analysis. IMPORTANT: Each session supports only ONE build at a time. For concurrent builds, open multiple sessions via ssh_shell_open and assign one build per session.

Inputs: command (required), session_id (required), cwd, classify, +2 more.

ssh_sftp_downloadA

Download a remote file from the board to local over SFTP, reusing an existing SSH session.

Inputs: local_path (required), session_id (required), remote_path (required).

ssh_sftp_uploadA

Upload a local file to the remote board over SFTP, reusing an existing SSH session.

Inputs: local_path (required), session_id (required), remote_path (required).

ssh_shell_closeB

Close an SSH shell session and release the connection.

Inputs: session_id (required).

ssh_shell_connectionA

Check active SSH connections on the remote board. Shows which client IPs are connected to the SSH service (port 22).

Inputs: session_id (required).

ssh_shell_execA

Send a command to an SSH shell session and wait for the output. Combines write + read in one call, with automatic completion detection (marker/prompt). IMPORTANT: Do NOT issue concurrent commands to the same session_id — the SSH shell is a single channel; concurrent calls will interleave output and corrupt results. Always wait for the previous command to finish before sending the next one. If you need parallel execution, open multiple sessions via ssh_shell_open.

Inputs: command (required), session_id (required), clear, timeoutMs.

ssh_shell_loginA

One-click SSH login: connect, detect PSH state, auto-unlock if locked, and return a ready session. Combines open + PSH detect + unlock into a single call.

Inputs: key, device, timeout.

ssh_shell_openA

Open an interactive SSH shell session to the board. Returns the initial banner output.

Inputs: device, timeout.

ssh_shell_readA

Read output from an SSH shell session. Do NOT call this concurrently with ssh_shell_exec/ssh_shell_write on the same session_id — concurrent access to the same SSH shell corrupts the output buffer.

Inputs: session_id (required), clear.

ssh_shell_send_ctrlA

Send a control character (Ctrl+C/U/D/Z) to an SSH shell session without appending a newline.

Inputs: key (required), session_id (required).

ssh_shell_writeA

Send a command to an SSH shell session. Do NOT call this concurrently with ssh_shell_exec/ssh_shell_read on the same session_id — concurrent access to the same SSH shell corrupts the output buffer.

Inputs: command (required), session_id (required), clear.

subnet_check_toolA

Analyze subnet information for a target IP address. Retrieves host IP, subnet mask, and gateway, calculates subnet range (network address, broadcast address, usable host range, CIDR), and determines whether the target IP falls within the same subnet as the host.

Inputs: target_ip (required).

version_toolA

Get the MCP server version and toolkit information

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.6/5.0

    Scored across 38 tools

    Disambiguation4/5

    Tool purposes are mostly clear due to transport prefixes and distinct verbs, but a few pairs blur boundaries: ssh_shell_open vs ssh_shell_login/serial_shell_login are convenience wrappers around open, and adb_exec vs adb_shell_exec differ only in whether a persistent session is used. The detailed descriptions help resolve these, so the overlap is manageable but not zero.

    Naming Consistency3/5

    The core convention is [transport]_[action] (e.g. ssh_shell_exec, serial_exec, adb_shell_open), but it is applied unevenly: serial_open/serial_close lack the 'shell' segment used by ssh_shell_open/adb_shell_open, adb_exec sits alongside adb_shell_exec with a different implication, and several tools use a _tool suffix (version_tool, port_scan_tool, greet_tool) while others do not. Still readable, but the conventions are mixed.

    Tool Count2/5

    At 38 tools, this exceeds the 25+ heavy threshold. The count is inflated by triplicating nearly identical session operations across SSH, serial, and ADB, plus a set of one-off utility tools; while systematic, it creates real selection overhead for agents.

    Completeness4/5

    The toolkit provides comprehensive lifecycle coverage for SSH, serial, and ADB sessions (open/read/write/exec/close), file transfer in both directions, U-Boot control, and environment metadata. Minor gaps exist—ADB file transfer is only available via generic adb_exec, and there is no dedicated reboot/port-forwarding tool—but these are workable without dead ends.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • sshops

      LckAndLove
      A
      license
      Not graded
      quality
      D
      maintenance
      A lightweight, zero-agent SSH operations tool that enables remote command execution, file transfer, and audit logging. It integrates as an MCP server for AI-driven infrastructure management.
      19 npm
      MIT

    • SSH MCP Server

      jiahuidegit
      A
      license
      A
      quality
      D
      maintenance
      A secure remote server management tool based on MCP protocol, supporting SSH connections, command execution, and SFTP file transfers.
      20
      16 npm
      6
      MIT