face-recognition-mcp-server

3DiVi Face SDK — MCP 服务

面向 AI 原生开发的人脸识别 MCP 服务。
本地部署 · 符合 GDPR · ISO 30107-3 活体检测 · 无需依赖云端。

---

项目简介

这是一个本地 Model Context Protocol 服务，将 3DiVi Face SDK Processing Block API 封装为可调用的工具。AI 编码 Agent（Claude Code、Cursor、Windsurf、VS Code Copilot）可以检测人脸、验证身份、执行活体检测并搜索人脸库，无需编写任何 SDK 集成代码。

所有处理都在开发者的计算机上进行。数据不会离开主机。

---

提供的工具

工具	Processing Block	输出
detect_faces	FACE_DETECTOR	边界框、关键点、俯仰角/偏航角/翻滚角
check_liveness	LIVENESS_ESTIMATOR	活体检测结果 + 置信度
assess_quality	QUALITY_ASSESSMENT_ESTIMATOR	质量分数、眼睛睁开标记
extract_template	FACE_TEMPLATE_EXTRACTOR	ContextTemplate（二进制，不含个人身份信息）
verify_face	VERIFICATION_MODULE	1:1 相似度分数 + 匹配结果
search_face	MATCHER_MODULE + DynamicTemplateIndex	1:N 排名匹配列表
estimate_attributes	AGE_ESTIMATOR + GENDER_ESTIMATOR	年龄、性别、置信度
estimate_emotion	EMOTION_ESTIMATOR	7 类情绪概率
detect_mask	MASK_ESTIMATOR	佩戴口罩/未佩戴口罩结果

---

快速开始

前置条件

• 已在计算机上安装 3DiVi Face SDK 3.29
• Python 3.9+
• 有效的 Face SDK 许可证

安装

git clone https://github.com/3divi/face-recognition-mcp-server.git
cd face-recognition-mcp-server
pip install -r server/python/requirements.txt

配置 Claude Code

将以下内容添加到 claude_desktop_config.json（或你的 Agent 的等效配置文件）：

{
  "mcpServers": {
    "3divi-face-sdk": {
      "command": "python",
      "args": ["/path/to/face-recognition-mcp-server/server/python/main.py"],
      "env": {
        "FACESDK_PATH": "/path/to/facesdk",
        "FACESDK_CONFIG": "/path/to/facesdk/conf/facerec.conf"
      }
    }
  }
}

试用

在任意项目中打开 Claude Code 并输入：

Integrate 3DiVi Face SDK for KYC verification — detect the face, run liveness,
extract a template, and compare against an enrolled template.

Claude Code 将直接调用 MCP 工具。无需编写 SDK 集成代码。

---

项目结构

face-recognition-mcp-server/
├── CLAUDE.md                        # Machine-readable API reference (read by AI agents)
├── README.md
├── LICENSE
├── server/
│   ├── python/                      # Phase 1 — stdio MCP server
│   │   ├── main.py                  # Entry point (JSON-RPC 2.0 over stdio)
│   │   ├── tools/
│   │   │   ├── detection.py         # detect_faces, check_liveness, assess_quality, detect_mask
│   │   │   ├── recognition.py       # extract_template, verify_face, search_face
│   │   │   └── attributes.py        # estimate_attributes, estimate_emotion
│   │   └── requirements.txt
│   └── nodejs/                      # Phase 2 — coming soon
├── reference-apps/
│   ├── kyc-onboarding/              # Phase 2
│   ├── access-control/              # Phase 2
│   └── emotion-analytics/           # Phase 3
└── docs/
    └── threshold-guide.md

---

本地部署为何重要

在许多受监管行业中，隐私法规（GDPR、BIPA、印度 DPDP）禁止将生物特征数据发送到第三方云 API。此 MCP 服务完全在本地运行——SDK 共享库在进程内处理图像，不会向任何地方传输生物特征数据。

注册表中唯一类似的生物特征 MCP 服务是 Microsoft Azure 的活体检测封装服务，它需要 Azure 云。此服务只需你已有的 SDK 许可证，无需其他条件。

---

相似度阈值指南

请参阅 docs/threshold-guide.md，了解针对不同用例的建议。

用例	建议阈值
实体门禁控制	0.97
企业考勤	0.95
KYC / 入职认证	0.93
访客监控名单	0.90
零售场景重新识别	0.85

---

许可证

MIT — MCP 服务为开源项目。底层的 3DiVi Face SDK 需要从 3divi.ai 单独获取许可证。

---

链接

• 3DiVi Face SDK 文档
• MCP 注册表条目 (即将推出)
• 开发者博客：30 分钟内将 3DiVi Face SDK 集成到 Claude Code (即将推出)