AI导哈

物联网设备控制服务器

Geekhouse IoT MCP Server 是一个用于控制运行在Raspberry Pi Pico W上的Geekhouse物联网设备的模型上下文协议服务器，提供LED控制、传感器读取、电机管理和LCD消息显示等功能。

  • by pavelanni
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 pavelanni/geekhouse-mcp

使用说明

Geekhouse物联网MCP服务器

用于控制运行在Raspberry Pi Pico W上的Geekhouse物联网设备的模型上下文协议（MCP）服务器。

该MCP服务器为Claude提供了本地工具，用于控制LED、读取传感器、管理电机，并通过HATEOAS REST API在LCD屏幕上显示消息。

特性

  • 8个MCP工具 用于面向工作流程的设备控制（LED、传感器、电机、LCD、发现）
  • 4 MCP资源 通过以下方式查询设备状态 @ 提及
  • 7个MCP提示 用于常见任务工作流和快速操作
  • 动态设备发现 通过MDNS/你好
  • 实时传感器监控 使用MCP资源订阅和基于TTL的缓存
  • 多设备支持 用于管理多个Pico W单元
  • HATEOAS REST API 与自动能力发现集成

安装

先决条件

  • 转到1.21或更高版本
  • 运行Geekhouse IoT固件的Raspberry Pi Pico W
  • Claude Desktop（用于MCP集成）

从源代码构建

git clone https://github.com/pavelanni/geekhouse-mcp.git
cd geekhouse-mcp
make build

Makefile会自动将Git的版本信息（标签、提交、构建日期）嵌入到二进制文件中。

替代构建方法：

# Build with make (recommended)
make build

# Build without version info (development)
make build-dev

# Or use go directly
go build -o geekhouse-mcp ./cmd/server

安装依赖项

make deps
# or
go mod download

配置

创建一个 config.yaml 文件：

server:
  discovery:
    enabled: true
    service_name: "_iot._tcp"
    timeout_seconds: 5

  devices:
    - name: "living_room"
      host: "192.168.1.130"
      port: 80

  cache:
    device_ttl_seconds: 30
    sensor_ttl_seconds: 5

logging:
  level: "info"
  format: "json"

看 config/config.example.yaml 了解完整的配置选项。

用法

检查版本

./build/geekhouse-mcp --version

输出：

Geekhouse IoT MCP Server
Version:    v1.0.0
Commit:     a1b2c3d
Build Date: 2025-11-14_19:13:26_UTC

Claude桌面集成

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "geekhouse": {
      "command": "/path/to/geekhouse-mcp",
      "args": ["--config", "/path/to/config.yaml"]
    }
  }
}

重新启动Claude Desktop，工具将自动显示。

可用工具

  • control_lighting -打开/关闭/切换LED
  • read_sensors -通过过滤读取传感器值
  • control_motor -操作直流电机
  • display_message -在LCD上显示文本
  • configure_sensor -更新传感器校准
  • list_devices -枚举可用设备
  • get_device_status -获取设备状态
  • discover_devices -Pico W设备的扫描网络

可用资源

MCP资源提供可查询的设备状态，您可以使用 @ 克劳德代码中提到：

  • @api://structure -完整的HAEOAS API结构，包括所有端点和导航链接
  • @device://led/{id} -单个LED状态（例如。， @device://led/1)
  • @device://sensor/{id} -单个传感器状态（例如。， @device://sensor/4)
  • @device://motor/{id} -单个电机状态（例如。， @device://motor/1)
  • @devices://leds -列出所有带有元数据的LED设备
  • @devices://sensors -列出所有带有元数据的传感器设备
  • @devices://motors -列出所有带有元数据的电机设备
  • @sensor-data://{id}/stream -实时传感器数据流（例如。， @sensor-data://4/stream)

Claude Code中的示例用法：

Show me the API structure: @api://structure
What sensors are available? @devices://sensors
What's the current temperature? @device://sensor/4

资源包括HATEOAS _links 显示可用操作和相关端点的部分。基于TTL的缓存确保了高效的性能，同时保持了新鲜的数据。

可用提示

MCP提示为常见任务提供预配置的工作流。通过Claude Desktop或Claude Code中的提示菜单访问它们：

  • system-status -获取所有设备和传感器的全面状态报告
  • lights-out -关闭系统中的所有灯
  • sensor-report -生成所有传感器读数的格式化报告（可选：按类型/位置过滤）
  • calibrate-sensor -传感器校准过程指南（要求：sensor_id）
  • emergency-shutdown -对所有设备执行安全停机顺序
  • monitor-sensor -设置传感器的实时监控（需要：sensor_id，可选：阈值）
  • device-inventory -列出所有具有功能的可用设备

示例用法：

在Claude Code中，提示有助于自动化常见的工作流程，而无需手动描述完整的操作序列。

发展

项目结构

geekhouse-mcp/
├── cmd/server/          # Entry point
├── internal/
│   ├── mcp/             # MCP server implementation
│   │   ├── tools/       # Tool handlers
│   │   ├── resources/   # Resource providers
│   │   └── prompts/     # Prompt templates
│   ├── rest/            # REST API client
│   ├── models/          # Data structures
│   └── config/          # Configuration loading
├── config/              # Example configs
└── docs/                # Documentation

在本地运行

# Run with make
make run

# Or with go directly
go run ./cmd/server --config config.yaml

# Or run the built binary
./build/geekhouse-mcp --config config.yaml

测试

make test
# or
go test ./...

生成文件目标

make build      # Build with version info (recommended)
make build-dev  # Build without version info
make clean      # Remove build artifacts
make test       # Run tests
make deps       # Download dependencies
make install    # Install to $GOPATH/bin
make version    # Show version info to be embedded
make run        # Run in development mode
make all        # Clean, deps, build
make help       # Show all available targets

建筑

看 MCP_实施_计划.md 详细的架构和设计决策。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！请打开问题或拉取请求。

相关项目

相关 MCP