AI导哈

Nintendo Switch控制API服务

EasyCon MCP服务是一个通过串行（USB/UART）使用EasyCon协议控制Nintendo Switch的HTTP/JSON API服务，支持按钮、摇杆、宏命令等控制功能。

  • by easyworld
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 easyworld/easycon-mcp-service

使用说明

EasyCon MCP服务

EasyCon MCP服务：用于Nintendo Switch通过串行（USB/UART）控制EasyCon协议的HTTP/JSON API。

此服务实现：

  • 串行生命周期：列出端口、连接/断开连接、状态
  • EasyCon握手：发送[A5，A5，81]并期待[80]
  • 开关控制：按钮、D-Pad（HAT）、摇杆和重置
  • 新：组合按钮、序列、宏、LED控制、控制器设置
  • 新：批处理操作、健康监测
  • 用于调试/扩展的原始发送/接收

需求

  • Python 3.9+
  • 一种使用EasyCon协议（115200 8N1）的串行设备

安装

pip install -r requirements.txt

跑

uvicorn mcp_service.server:app --host 0.0.0.0 --port 8000

api参考

连接管理

  • 获取 /ports -列出可用串行端口
  • 发布 /connect -连接到串行端口
  • 发布 /disconnect -断开与串行端口的连接
  • 获取 /status -获取连接状态
  • 发布 /init -初始化设备（握手）

基本控制

  • 发布 /press/button -按下一个按钮
  • 发布 /press/hat -按D-Pad方向
  • 发布 /stick -控制模拟棒
  • 发布 /reset -发送重置命令

高级控制（新）

  • 发布 /press/combo -同时按下多个按钮
  • 发布 /sequence -重复执行一系列操作
  • 发布 /batch -批量执行多个命令

宏观系统（新）

  • 发布 /macro/save -保存宏
  • 获取 /macro/list -列出所有已保存的宏
  • 获取 /macro/{name} -获取宏详细信息
  • 删除 /macro/{name} -删除宏
  • 发布 /macro/execute -执行已保存的宏

设备控制（新）

  • 发布 /led -控制装置LED（开/关）
  • 获取 /version -获取固件版本
  • 发布 /controller/mode -更改控制器模式（Pro/JoyCon）
  • 发布 /controller/color -更改控制器颜色
  • 发布 /unpair -从控制台上拔下控制器

公用事业

  • 获取 /health -健康检查端点
  • 获取 /buttons -列出所有可用按钮
  • 获取 /directions -列出所有可用的HAT路线
  • 发布 /raw/send -发送原始字节

例子

基本用法

# 1) List ports
curl http://localhost:8000/ports

# 2) Connect
curl -X POST http://localhost:8000/connect -H "Content-Type: application/json" \
     -d '{"port":"/dev/ttyUSB0","baud":115200}'

# 3) Handshake
curl -X POST http://localhost:8000/init

# 4) Press A for 50ms
curl -X POST http://localhost:8000/press/button -H "Content-Type: application/json" \
     -d '{"button":"A","durationMs":50}'

# 5) Reset
curl -X POST http://localhost:8000/reset

# 6) Disconnect
curl -X POST http://localhost:8000/disconnect

组合按钮

# Press A+B simultaneously for 100ms
curl -X POST http://localhost:8000/press/combo -H "Content-Type: application/json" \
     -d '{"buttons":["A","B"],"durationMs":100}'

# Press L+R (screenshot combo)
curl -X POST http://localhost:8000/press/combo -H "Content-Type: application/json" \
     -d '{"buttons":["L","R"],"durationMs":50}'

序列

# Execute a sequence: press A, wait, press B, repeat 3 times
curl -X POST http://localhost:8000/sequence -H "Content-Type: application/json" \
     -d '{
  "steps": [
    {"type":"button","button":"A","durationMs":50},
    {"type":"wait","durationMs":100},
    {"type":"button","button":"B","durationMs":50}
  ],
  "repeatCount": 3
}'

宏

# Save a macro
curl -X POST http://localhost:8000/macro/save -H "Content-Type: application/json" \
     -d '{
  "name": "farm_berries",
  "steps": [
    {"type":"button","button":"A","durationMs":50},
    {"type":"wait","durationMs":500},
    {"type":"button","button":"A","durationMs":50},
    {"type":"wait","durationMs":1000}
  ]
}'

# List macros
curl http://localhost:8000/macro/list

# Execute macro 10 times
curl -X POST http://localhost:8000/macro/execute -H "Content-Type: application/json" \
     -d '{"name":"farm_berries","repeatCount":10}'

# Delete macro
curl -X DELETE http://localhost:8000/macro/farm_berries

批量操作

# Execute multiple commands in one request
curl -X POST http://localhost:8000/batch -H "Content-Type: application/json" \
     -d '{
  "commands": [
    {"type":"button","button":"HOME","durationMs":100},
    {"type":"wait","durationMs":1000},
    {"type":"button","button":"A","durationMs":50},
    {"type":"combo","buttons":["A","B"],"durationMs":100}
  ]
}'

设备控制

# Turn LED on
curl -X POST http://localhost:8000/led -H "Content-Type: application/json" \
     -d '{"state":true}'

# Get firmware version
curl http://localhost:8000/version

# Change to Pro Controller mode
curl -X POST http://localhost:8000/controller/mode -H "Content-Type: application/json" \
     -d '{"mode":0}'

# Change controller color (red body, white buttons)
curl -X POST http://localhost:8000/controller/color -H "Content-Type: application/json" \
     -d '{"body_r":255,"body_g":0,"body_b":0,"button_r":255,"button_g":255,"button_b":255}'

公用事业

# Health check
curl http://localhost:8000/health

# List available buttons
curl http://localhost:8000/buttons

# List available directions
curl http://localhost:8000/directions

API文档

服务器运行后，请访问：

  • Swagger用户界面: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

动作步骤类型

使用时 /sequence, /macro/save，或批处理操作，支持以下操作类型：

类型 必填字段 可选字段 描述
button button durationMs 按下一个按钮
combo buttons durationMs 同时按下多个按钮
hat direction durationMs 按D-Pad方向
stick - lx, ly, rx, ry, durationMs 控制模拟棒
wait - durationMs 等待/延迟

按钮名称

A、 B、X、Y、L、R、ZL、ZR、加号、减号、LCLICK、RCLICK、HOME、CAPTURE

方向名称

顶部、右顶部、右侧、右底部、底部、左底部、左侧、左顶部、中央

控制器模式

  • 0：Pro控制器
  • 1：Joy Con（左）
  • 2：乔伊康（右）

备注

  • 串行设置固定为115200 8N1。
  • 每个媒体都会发出行动→ 等待 durationMs → 发送RESET。
  • 握手将在发送之前清除过时的字节。
  • 宏存储在内存中，将在服务器重新启动时丢失。
  • 对于持久宏，可以考虑将它们保存到文件或数据库中。

许可证

麻省理工学院

相关 MCP