@wefi-ai/ekyc-suite-mcp

v1.0.1

Published

13 days ago

KYC / eKYC identity verification MCP server with 8 financial-grade tools: face comparison, photo and video liveness, ID card OCR, bank card OCR, driver's license OCR, vehicle license OCR, and image labeling.

eKYC Suite MCP Server

Financial-grade electronic identity verification toolkit for AI agents, exposed as 8 MCP tools.

eKYC身份核验套件 MCP 服务端，提供8项金融级身份核验工具。

Repository: https://github.com/wefi-ai/eKYC-suite

Capabilities

| # | Tool | Description | |---|------|-------------| | 1 | face_compare | Compare two face photos, return similarity score 0-100 | | 2 | photo_liveness_detect | Detect if a photo is genuine or forged (AI-generated, deepfake, replay) | | 3 | video_liveness_detect | Detect if a video is genuine or deepfake (auto-retries on network errors) | | 4 | id_card_ocr | Extract info from Chinese national ID card (portrait or emblem side) | | 5 | bank_card_ocr | Extract card number and expiry from bank card photo | | 6 | driver_license_ocr | Extract info from Chinese driver's license (main page only) | | 7 | vehicle_license_ocr | Extract info from Chinese vehicle license (main + supplementary page) | | 8 | media_labeling | Analyze image/video for 15+ attribute labels (mask, coercion, tattoo, etc.) |

Quick Start

1. Install

npm install ekyc-suite-mcp

Or clone and install dependencies:

git clone <repository-url>
cd ekyc-suite-mcp
npm install

2. Configure Credentials

Copy .env.example to .env and fill in your API credentials:

cp .env.example .env

You need two separate credential sets:

Key A (KYC_APPID + KYC_SECRET): Enables capabilities 1-7 (face comparison, liveness, OCR)
Key B (LABEL_APPID + LABEL_SECRET): Enables capability 8 (media labeling)

Either key alone works — unconfigured capabilities will return a clear error message.

How to obtain credentials:

Contact Huiyan tech support (WeChat: blue-201809)
Or self-service at Tencent Cloud Face Verification Console

⚠️ IMPORTANT: Fill in test ID and test Secret (free 100 calls). Do NOT use production credentials — production IDs incur charges billed by the upstream provider. 请使用测试ID和测试Secret（免费100次），不要使用正式ID，正式ID会产生计费。

3. Run

node server.mjs

4. Connect to Your MCP Client

Add to your MCP client configuration (e.g., Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "ekyc-suite": {
      "command": "node",
      "args": ["/path/to/ekyc-suite-mcp/server.mjs"],
      "env": {
        "KYC_APPID": "your_kyc_appid",
        "KYC_SECRET": "your_kyc_secret",
        "LABEL_APPID": "your_label_appid",
        "LABEL_SECRET": "your_label_secret"
      }
    }
  }
}

Input Formats

All image/video parameters accept three input formats:

File path: /path/to/photo.jpg
URL: https://example.com/photo.jpg (public URLs only; private/internal network URLs are blocked for security)
Base64 string: Raw base64-encoded content

Maximum file size: 20MB. Videos must be ≤20 seconds.

Tool Details

face_compare

{
  "photo1": "/path/to/selfie.jpg",
  "photo2": "/path/to/id_photo.jpg",
  "sourcePhotoType": "2"
}

Returns { "success": true, "similarity": "95.7" }. Score ≥80 = high-confidence same person.

photo_liveness_detect / video_liveness_detect

{ "file": "/path/to/face_photo.jpg" }

Returns risk level 1-3 with attack type classification (replay, synthetic, adversarial, etc.).

id_card_ocr

{ "image": "/path/to/id_card.jpg", "side": "0" }

side: 0 = portrait side (front), 1 = national emblem side (back).

media_labeling

{
  "file": "/path/to/photo.jpg",
  "labels": "A02,A14,B03",
  "type": "image"
}

Available label codes (max 5 per request):

Portrait labels: A01 (facial mask), A02 (medical mask), A04 (headphones), A05 (nudity), A06 (sunglasses), A09 (coercion), A10 (unconscious/asleep), A11 (on phone), A13 (tattoo), A14 (hat), A15 (critical patient)

Environment labels: B02 (multiple people), B03 (inside car), B06 (hotel room), B07 (car dealership)

Security & Privacy

This software does not store, cache, or retain any submitted data.

API verification results are for reference only and do not constitute legal identity confirmation. This software must not be used as the sole basis for automated decisions that produce legal effects or significant consequences for individuals. Users should implement appropriate business logic and human review processes for high-stakes identity decisions.

Rate Limits

Capabilities 1-7 (KYC): 100 calls per appid (test quota)
Capability 8 (Media Labeling): Concurrency-limited, default 1 concurrent request

Legal Notice