yo-onvif-mcp

一个基于 Node.js 和 TypeScript 实现的 ONVIF 网络摄像头控制和画面识别 MCP (Model Context Protocol) 工具，支持通过 MCP 协议执行网络摄像头控制、画面捕获和 OCR 识别。

功能特性

• ✅ 支持 ONVIF 协议的网络摄像头控制
• ✅ 摄像头画面捕获和 OCR 识别
• ✅ 支持环境变量和命令行参数配置
• ✅ 支持通过 npx 直接调用
• ✅ 自动初始化摄像头设备
• ✅ 友好的错误提示和配置指引
• ✅ 支持动态重新初始化摄像头

安装

从 npm 安装（发布后）

npm install -g yo-onvif-mcp
# 或
pnpm add -g yo-onvif-mcp

本地开发安装

# 克隆或下载项目
cd yo-onvif-mcp

# 安装依赖
pnpm install

# 编译项目
pnpm build

配置

方式 1: 环境变量配置

export ONVIF_USERNAME=admin
export ONVIF_PASSWORD=admin123
export ONVIF_XADDR=http://192.168.31.10:80/onvif/device_service

方式 2: 命令行参数配置

npx yo-onvif-mcp --args '{"username":"admin","password":"admin123","xaddr":"http://192.168.31.10:80/onvif/device_service"}'

注意: 命令行参数的优先级高于环境变量。

配置参数说明

| 参数 | 说明 | 示例 | |------|------|------| | username | ONVIF 设备的用户名 | admin | | password | ONVIF 设备的密码 | admin123 | | xaddr | ONVIF 设备服务地址 | http://192.168.31.10:80/onvif/device_service |

使用方式

直接运行

# 使用环境变量配置
npx yo-onvif-mcp

# 使用命令行参数配置
npx yo-onvif-mcp --args '{"username":"admin","password":"admin123","xaddr":"http://192.168.31.10:80/onvif/device_service"}'

在 Cursor 中配置

在 Cursor 的 MCP 配置文件中添加：

{
  "mcpServers": {
    "yo-onvif-mcp": {
      "command": "npx",
      "args": [
        "yo-onvif-mcp",
        "--args",
        "{\"username\":\"admin\",\"password\":\"admin123\",\"xaddr\":\"http://192.168.31.10:80/onvif/device_service\"}"
      ]
    }
  }
}

或者使用环境变量：

{
  "mcpServers": {
    "yo-onvif-mcp": {
      "command": "npx",
      "args": ["yo-onvif-mcp"],
      "env": {
        "ONVIF_USERNAME": "admin",
        "ONVIF_PASSWORD": "admin123",
        "ONVIF_XADDR": "http://192.168.31.10:80/onvif/device_service"
      }
    }
  }
}

MCP 工具说明

1. onvif_capture_and_recognize

捕获摄像头画面并进行 OCR 识别。

参数:

• question (必需): 识别问题，例如："画面中有什么？"、"检测是否有人员"等

示例:

{
  "name": "onvif_capture_and_recognize",
  "arguments": {
    "question": "画面中有什么？"
  }
}

返回:

{
  "success": true,
  "message": "请求成功",
  "data": {
    // OCR 识别结果
  }
}

2. onvif_reinitialize

重新初始化摄像头设备。可以传入新的配置参数，如果不传入则使用环境变量或命令行参数中的配置。

参数:

• username (可选): ONVIF 用户名
• password (可选): ONVIF 密码
• xaddr (可选): ONVIF 设备地址

示例:

{
  "name": "onvif_reinitialize",
  "arguments": {
    "username": "admin",
    "password": "admin123",
    "xaddr": "http://192.168.31.10:80/onvif/device_service"
  }
}

返回:

{
  "content": [
    {
      "type": "text",
      "text": "摄像头初始化成功！\n设备地址: http://192.168.31.10:80/onvif/device_service\n用户名: admin"
    }
  ]
}

MCP 资源

onvif://status

查看摄像头初始化状态和配置信息。

返回示例:

{
  "initialized": true,
  "error": null,
  "config": {
    "username": "admin",
    "xaddr": "http://192.168.31.10:80/onvif/device_service"
  }
}

二次开发

项目结构

yo-onvif-mcp/
├── src/
│   ├── index.ts          # MCP 服务器主入口
│   ├── cli.ts            # CLI 入口文件
│   ├── config.ts         # 配置管理模块
│   ├── camera.ts         # 摄像头控制和 OCR 识别
│   └── types/            # TypeScript 类型定义
│       ├── node-onvif.d.ts
│       └── getmac.d.ts
├── dist/                 # 编译输出目录
├── package.json
├── tsconfig.json
└── README.md

开发环境设置

# 安装依赖
pnpm install

# 开发模式（自动编译）
pnpm dev

# 构建项目
pnpm build

# 测试
pnpm test

核心模块说明

src/config.ts - 配置管理

提供配置读取和验证功能：

import { getValidConfig, type OnvifConfig } from './config.js'

// 获取有效配置
const config = getValidConfig()

// 验证配置
if (config) {
  // 使用配置
}

主要函数:

• getConfigFromEnv(): 从环境变量读取配置
• getConfigFromArgs(): 从命令行参数读取配置
• getConfig(): 合并配置（命令行参数优先）
• validateConfig(): 验证配置完整性
• getValidConfig(): 获取完整配置或 null

src/camera.ts - 摄像头控制

提供摄像头初始化和 OCR 识别功能：

import { init, captureImageAndOcr, OCR } from './camera.js'

// 初始化摄像头
await init(username, password, xaddr)

// 捕获画面并识别
const result = await captureImageAndOcr(username, password, question)

// 直接 OCR 识别（需要图片 Buffer）
const ocrResult = await OCR(imageBuffer, question)

主要函数:

• init(username, password, xaddr): 初始化 ONVIF 设备
• captureImageAndOcr(username, password, question): 捕获画面并 OCR 识别
• OCR(image, question): 对图片进行 OCR 识别

src/index.ts - MCP 服务器

MCP 服务器主文件，处理工具调用和资源请求。

添加新工具:

// 在 ListToolsRequestSchema 处理器中添加工具定义
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      // ... 现有工具
      {
        name: 'your_new_tool',
        description: '工具描述',
        inputSchema: {
          type: 'object',
          properties: {
            // 参数定义
          },
        },
      },
    ],
  }
})

// 在 CallToolRequestSchema 处理器中添加工具实现
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params
  
  if (name === 'your_new_tool') {
    // 实现工具逻辑
    return {
      content: [
        {
          type: 'text',
          text: '结果',
        },
      ],
    }
  }
})

扩展功能示例

添加新的摄像头控制功能

1. 在 src/camera.ts 中添加新函数：

/**
 * 控制摄像头 PTZ（云台控制）
 */
export async function controlPTZ(
  username: string,
  password: string,
  action: 'up' | 'down' | 'left' | 'right' | 'zoom_in' | 'zoom_out'
) {
  if (!device) {
    throw new Error('设备未初始化')
  }
  
  // 实现 PTZ 控制逻辑
  // ...
}

2. 在 src/index.ts 中添加对应的 MCP 工具。

添加新的识别服务

修改 src/camera.ts 中的 OCR 函数，或创建新的识别函数：

/**
 * 使用自定义识别服务
 */
export async function customRecognize(image: Buffer, question: string, apiUrl: string) {
  const formData = new FormData()
  const blob = new Blob([new Uint8Array(image)], { type: 'image/jpeg' })
  formData.append('file', blob, 'snapshot.jpg')
  formData.append('question', question)
  
  return fetch(apiUrl, {
    method: 'POST',
    body: formData,
  }).then(res => res.json())
}

类型定义

项目使用 TypeScript，类型定义位于 src/types/ 目录：

• node-onvif.d.ts: ONVIF 设备类型定义
• getmac.d.ts: MAC 地址获取库类型定义

构建和发布

# 构建项目
pnpm build

# 发布到 npm（需要先登录）
npm login
npm publish

故障排查

摄像头初始化失败

1. 检查网络连接: 确保设备地址可访问
2. 验证凭据: 确认用户名和密码正确
3. 检查 ONVIF 支持: 确认设备支持 ONVIF 协议
4. 查看错误信息: 使用 onvif_reinitialize 工具查看详细错误

画面识别失败

1. 检查摄像头初始化状态: 使用 onvif://status 资源查看状态
2. 验证快照 URI: 确认设备支持快照功能
3. 检查网络: 确保可以访问快照 URI
4. 查看识别服务: 确认 OCR 服务可用

配置问题

1. 环境变量未生效: 确保在运行前设置了环境变量
2. 命令行参数格式错误: 确保 JSON 格式正确
3. 参数优先级: 命令行参数会覆盖环境变量

依赖说明

• @modelcontextprotocol/sdk: MCP 协议 SDK
• node-onvif: ONVIF 设备控制库
• getmac: MAC 地址获取（用于设备标识）

许可证

ISC

作者

yokochen ([email protected])

贡献

欢迎提交 Issue 和 Pull Request！