face-recognition-mcp-server

3DiVi Face SDK — MCP Server

The face recognition MCP server for AI-native development.
On-premise · GDPR-compliant · ISO 30107-3 liveness · No cloud dependency.

---

What this is

A local Model Context Protocol server that wraps the 3DiVi Face SDK Processing Block API as callable tools. AI coding agents (Claude Code, Cursor, Windsurf, VS Code Copilot) can detect faces, verify identity, run liveness checks, and search a face gallery — without writing a single line of SDK integration code.

All processing runs on the developer's machine. No data leaves the host.

---

Tools exposed

Tool	Processing Block	Output
detect_faces	FACE_DETECTOR	Bounding boxes, landmarks, pitch/yaw/roll
check_liveness	LIVENESS_ESTIMATOR	Liveness verdict + confidence
assess_quality	QUALITY_ASSESSMENT_ESTIMATOR	Quality score, eyes-open flag
extract_template	FACE_TEMPLATE_EXTRACTOR	ContextTemplate (binary, no PII)
verify_face	VERIFICATION_MODULE	1:1 similarity score + match verdict
search_face	MATCHER_MODULE + DynamicTemplateIndex	1:N ranked match list
estimate_attributes	AGE_ESTIMATOR + GENDER_ESTIMATOR	Age, gender, confidence
estimate_emotion	EMOTION_ESTIMATOR	7-class emotion probabilities
detect_mask	MASK_ESTIMATOR	Masked/unmasked verdict

---

Quick start

Prerequisites

• 3DiVi Face SDK 3.29 installed on your machine
• Python 3.9+
• A valid Face SDK licence

Install

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

Configure Claude Code

Add to your claude_desktop_config.json (or equivalent for your 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"
      }
    }
  }
}

Try it

Open Claude Code in any project and type:

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

Claude Code will call the MCP tools directly. No SDK integration code required.

---

Project structure

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

---

Why on-premise matters

Privacy regulations (GDPR, BIPA, India DPDP) prohibit sending biometric data to third-party cloud APIs in many regulated industries. This MCP server runs entirely local — the SDK shared libraries process images in-process, and no biometric data is transmitted anywhere.

The only competing biometric MCP server in the registry is Microsoft Azure's liveness wrapper, which requires Azure cloud. This server requires nothing beyond the SDK licence you already have.

---

Similarity threshold guide

See docs/threshold-guide.md for use-case-specific recommendations.

Use case	Recommended threshold
Physical access control	0.97
Enterprise time/attendance	0.95
KYC / onboarding	0.93
Visitor watchlist	0.90
Retail re-identification	0.85

---

Licence

MIT — the MCP server is open source. The underlying 3DiVi Face SDK requires a separate licence from 3divi.ai.

---

Links

• 3DiVi Face SDK documentation
• MCP registry listing (coming soon)
• Developer blog: Integrating 3DiVi Face SDK with Claude Code in 30 minutes (coming soon)