内容
# MCP Homescan 服务器
[](https://www.npmjs.com/package/mcp-homescan)
[](https://github.com/aplaceforallmystuff/mcp-homescan/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
用于家庭网络发现和安全扫描的MCP服务器。发现本地网络上的设备，识别制造商，标记潜在的安全问题，并导出到Obsidian库存格式。
## 为什么使用此工具？
如果你正在管理家庭或小型办公网络，这个MCP服务器可以帮助你：
- **发现所有设备** - 通过ARP表扫描找到连接到网络的所有设备
- **识别制造商** - 自动将MAC地址映射到制造商
- **标记安全问题** - 识别未知或潜在风险的设备（某些地区的IoT设备等）
- **跟踪变化** - 检测扫描之间新增或移除的设备
- **记录网络** - 导出到markdown格式，适用于Obsidian或其他文档系统
## 功能
| 类别 | 功能 |
|----------|-------------|
| **发现** | 基于ARP的网络扫描，ping扫描以实现全面发现 |
| **识别** | MAC地址制造商查找，设备分类 |
| **安全** | 标记未知设备，识别潜在的IoT风险 |
| **变更检测** | 比较扫描结果，跟踪新增/移除的设备 |
| **导出** | Markdown和JSON格式，兼容Obsidian库存 |
## 先决条件
- Node.js 18+
- macOS 或 Linux（使用 `arp` 命令）
- 可以访问本地子网
## 安装
### 使用 npm（推荐）
```bash
npx mcp-homescan
```
或全局安装：
```bash
npm install -g mcp-homescan
```
### 从源码安装
```bash
git clone https://github.com/aplaceforallmystuff/mcp-homescan.git
cd mcp-homescan
npm install
npm run build
```
## 配置
### 对于 Claude Desktop
将以下内容添加到您的Claude Desktop配置文件中：
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"homescan": {
"command": "npx",
"args": ["-y", "mcp-homescan"],
"env": {
"HOMESCAN_SUBNET": "192.168.1"
}
}
}
}
```
### 对于 Claude Code
将以下内容添加到 `~/.claude.json`：
```json
{
"mcpServers": {
"homescan": {
"command": "npx",
"args": ["-y", "mcp-homescan"],
"env": {
"HOMESCAN_SUBNET": "192.168.1"
}
}
}
}
```
### 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `HOMESCAN_SUBNET` | 要扫描的网络子网（例如 `192.168.1`） | `192.168.1` |
## 使用示例
### 网络发现
> "扫描我的家庭网络以查找设备"
> "我的网络上有哪些设备？"
> "刷新网络扫描并显示所有设备"
### 设备调查
> "192.168.1.34上的设备是什么？"
> "查找MAC地址 aa:bb:cc:dd:ee:ff 的制造商"
### 安全审查
> "在我的网络上显示所有标记的设备"
> "有哪些我应该调查的未知设备？"
### 变更跟踪
> "自上次扫描以来是否有新增设备？"
> "显示我的网络变化"
### 文档
> "将我的网络库存导出到markdown"
> "生成网络报告"
## 可用工具
| 工具 | 描述 |
|------|-------------|
| `homescan_discover` | 发现本地网络上的所有设备 |
| `homescan_device` | 获取指定IP地址的设备详情 |
| `homescan_mac_lookup` | 根据MAC地址查找制造商 |
| `homescan_report` | 生成综合网络发现报告 |
| `homescan_export` | 将设备导出到markdown或JSON格式 |
| `homescan_diff` | 比较当前扫描与上一次扫描，显示变化 |
| `homescan_flagged` | 列出标记为安全审查的设备 |
## 开发
```bash
# 监听模式用于开发
npm run watch
# 编译TypeScript
npm run build
# 本地运行
node dist/index.js
```
## 故障排除
### "未找到设备"
确保您在同一个网络段上，并且子网配置正确。尝试运行 `refresh: true` 以首先执行ping扫描。
### "权限被拒绝" 错误
ARP表在某些系统上可能需要提升的权限。尝试使用 `sudo` 运行。
### 扫描中缺少设备
某些设备可能不会响应ARP查询。使用 `homescan_discover` 并设置 `refresh: true` 以首先执行网络ping扫描。
### 子网错误
检查您的网络配置并更新 `HOMESCAN_SUBNET` 以匹配您的本地网络（常见值：`192.168.1`、`192.168.0`、`10.0.0`）。
## 安全说明
- 此工具仅扫描您的本地网络
- 不会向外部发送任何数据
- 标记的设备仅为建议 - 请在采取行动前验证
- 请参阅 [SECURITY.md](SECURITY.md) 以获取漏洞披露信息
## 路线图
请参阅 [ROADMAP.md](ROADMAP.md) 以获取计划的工作和范围估计。
## 贡献
欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取指南。
## 许可证
MIT - 请参阅 [LICENSE](LICENSE) 以获取详细信息。
## 链接
- [模型上下文协议](https://modelcontextprotocol.io)
- [MCP 规范](https://spec.modelcontextprotocol.io)
- [GitHub 仓库](https://github.com/aplaceforallmystuff/mcp-homescan)
