Uses GPT-4o through OpenAI's API for high-precision PII detection in text, enabling accurate identification of personal identifiable information across Korean and English content
MCP PII Tools
Model Context Protocol (MCP)을 위한 PII(개인식별정보) 탐지, 익명화, 암호화 및 복호화 도구입니다.
🚀 주요 기능
- 고정밀 PII 탐지: GPT-4o 기반
langextract
를 사용한 정확한 PII 탐지 - 다양한 PII 유형 지원: 이름, 이메일, 전화번호, 여권번호, 주소, 신용카드번호, 주민등록번호 등
- 실시간 익명화: 탐지된 PII를 즉시 익명화 처리
- 고급 암호화: 결정론적 암호화(검색 가능) 및 FPE(형식 유지 암호화) 지원
- 완전한 복호화: 암호화된 텍스트를 원본으로 복원
- 일괄 처리: 여러 텍스트를 효율적으로 처리
- MCP 호환: Model Context Protocol 표준을 준수
📦 설치 요구사항
1. uv 설치 (권장)
2. 프로젝트 설치
3. pip 사용 (대안)
🔐 암호화 방식
결정론적 암호화 (Deterministic Encryption)
- 용도: 이름, 주소, 이메일
- 특징: 같은 입력 → 같은 암호문 (검색 가능)
- 알고리즘: AES-CBC with PBKDF2
- 출력: Base64 인코딩
FPE (Format Preserving Encryption)
- 용도: 전화번호, 신용카드번호, 여권번호, 주민등록번호, 은행계좌번호
- 특징: 원본 형식 유지 (010-1234-5678 → 808-2523-9129)
- 알고리즘: 컨텍스트 기반 결정론적 변환
- 출력: 동일한 형식의 암호문
🔧 사용법
1. 기본 PII 탐지
2. 텍스트 처리 (탐지 + 익명화)
3. 일괄 처리
4. 익명화 처리
5. 개별 PII 항목 암호화
6. 텍스트 전체 암호화/복호화
🛠️ MCP Tools
1. detect_pii
텍스트에서 PII를 탐지합니다.
매개변수:
text
(string): 분석할 텍스트
반환값:
2. process_text
텍스트에서 PII를 탐지하고 익명화 처리합니다.
매개변수:
text
(string): 처리할 텍스트
반환값:
3. batch_process
여러 텍스트를 일괄적으로 처리합니다.
매개변수:
texts
(array): 처리할 텍스트 리스트
반환값:
4. anonymize_text
PII 항목들을 사용하여 텍스트를 익명화합니다.
매개변수:
text
(string): 원본 텍스트pii_items
(array): PII 항목들
반환값:
5. encrypt_pii_item
개별 PII 항목을 암호화합니다.
매개변수:
pii_value
(string): 암호화할 PII 값pii_type
(string): PII 유형 (이름, 전화번호, 이메일 등)
반환값:
6. decrypt_pii_item
암호화된 PII 항목을 복호화합니다.
매개변수:
encrypted_value
(string): 복호화할 암호화된 값pii_type
(string): PII 유형
반환값:
7. encrypt_text_pii
텍스트에서 PII를 탐지하고 모든 PII를 암호화합니다.
매개변수:
text
(string): 처리할 텍스트
반환값:
8. decrypt_text_pii
암호화된 텍스트에서 PII를 복호화합니다.
매개변수:
encrypted_text
(string): 암호화된 텍스트encrypted_items
(object): 원본값 → 암호화값 매핑
반환값:
🎯 지원하는 PII 유형
유형 | 한국어 | 영어 | 예시 | 암호화 방식 |
---|---|---|---|---|
이름 | 이름 | name | 김철수, Rachel Lim | 결정론적 |
이메일 | 이메일 | kim@example.com | 결정론적 | |
주소 | 주소 | address | 서울시 강남구 테헤란로 123 | 결정론적 |
전화번호 | 전화번호 | phone | 010-1234-5678 | FPE |
여권번호 | 여권번호 | passport_number | M31143886 | FPE |
신용카드번호 | 신용카드번호 | credit_card | 4532-1234-5678-9012 | FPE |
주민등록번호 | 주민등록번호 | ssn | 123456-1234567 | FPE |
은행계좌번호 | 은행계좌번호 | bank_account | 123-456-789012 | FPE |
⚡ 성능 특성
- 정확도: 100% (GPT-4o 기반)
- 처리 시간: 평균 1.3초/텍스트 (탐지), 0.1초/텍스트 (암호화/복호화)
- 지원 언어: 한국어, 영어, 혼합 텍스트
- 동시 처리: 일괄 처리 지원
- 암호화 성능: 초당 수천 건 처리 가능
🔒 보안 고려사항
- PII 탐지: OpenAI API를 통한 텍스트 전송이 발생할 수 있습니다
- 암호화: 모든 암호화/복호화는 로컬에서 처리됩니다
- 키 관리:
PII_MASTER_KEY
환경변수로 마스터 키 설정 필요 - 데이터 보호: 암호화된 데이터는 검색 가능하지만 원본 복원 불가능
- 형식 유지: FPE를 통해 데이터베이스 스키마 변경 없이 암호화 가능
📝 예제 실행
uv 사용 (권장)
pip 사용
🔧 환경 설정
1. 환경변수 설정
방법 1: 템플릿 파일 사용 (권장)
방법 2: 직접 생성
필수 환경변수
OPENAI_API_KEY
: OpenAI API 키 (https://platform.openai.com/api-keys)PII_MASTER_KEY
: PII 암호화용 마스터 키 (32자 이상 권장)
마스터 키 생성 방법
2. MCP 서버 실행
uv 사용 (권장):
pip 사용:
3. 사용 가능한 MCP Tools
detect_pii
: PII 탐지process_text
: PII 탐지 + 익명화batch_process
: 일괄 처리anonymize_text
: 익명화encrypt_pii_item
: 개별 PII 암호화decrypt_pii_item
: 개별 PII 복호화encrypt_text_pii
: 텍스트 전체 암호화decrypt_text_pii
: 텍스트 전체 복호화
🖥️ Claude Desktop 설정
1. Claude Desktop MCP 설정
Claude Desktop에서 MCP 서버를 사용하려면 설정 파일을 수정해야 합니다.
macOS 설정 파일 위치:
Windows 설정 파일 위치:
2. 설정 파일 내용
권장 설정 (uv 사용):
중요한 설정 포인트:
- uv 전체 경로 사용:
command
에uv
의 전체 경로를 지정- macOS (Homebrew):
/opt/homebrew/bin/uv
- macOS (직접 설치):
~/.cargo/bin/uv
- Linux:
~/.cargo/bin/uv
- macOS (Homebrew):
- 디렉터리 명시:
--directory
옵션으로 프로젝트 디렉터리 지정- Claude Desktop이 실행될 때 올바른 가상환경을 찾을 수 있도록 함
pyproject.toml
이 있는 디렉터리를 정확히 지정해야 함
- 상대 경로 사용:
args
에서 스크립트 파일명만 사용--directory
로 작업 디렉터리가 설정되므로 상대 경로로 충분
대안 설정 (pip 사용):
3. 설정 방법
- Claude Desktop 종료
- 설정 파일 편집 (위 경로의 JSON 파일)
- Claude Desktop 재시작
- MCP 서버 연결 확인
4. 사용 예시
Claude Desktop에서 다음과 같이 사용할 수 있습니다:
🖥️ Cursor 설정
1. Cursor MCP 설정
Cursor에서 MCP 서버를 사용하려면 설정을 추가해야 합니다.
설정 파일 위치:
2. 설정 파일 내용
3. Cursor에서 사용
- Cursor 설정 열기 (Cmd/Ctrl + ,)
- MCP 설정 추가
- Cursor 재시작
- MCP 도구 사용
🔧 수동 테스트
1. MCP 서버 직접 테스트
uv 사용 (권장):
pip 사용:
2. 개별 도구 테스트
uv 사용 (권장):
pip 사용:
🚨 문제 해결
1. MCP 서버 연결 실패
- 환경변수 확인:
OPENAI_API_KEY
,PII_MASTER_KEY
설정 확인 - uv 설치 확인:
uv --version
으로 uv가 설치되어 있는지 확인 - 의존성 설치 확인:
uv sync
로 모든 의존성이 설치되었는지 확인 - 파일 권한 확인: 스크립트 파일에 실행 권한이 있는지 확인
1.1. 모듈을 찾을 수 없는 오류 (ModuleNotFoundError)
증상: ModuleNotFoundError: No module named 'dotenv'
또는 ModuleNotFoundError: No module named 'langextract'
원인: Claude Desktop이 실행할 때 올바른 가상환경을 찾지 못함
해결 방법:
- uv 전체 경로 사용:
- 디렉터리 명시:
- uv 경로 확인:
- 수동 테스트:
2. 도구가 보이지 않는 경우
- Claude Desktop 재시작: 설정 변경 후 반드시 재시작
- 로그 확인: Claude Desktop 로그에서 오류 메시지 확인
- 설정 파일 문법: JSON 문법이 올바른지 확인
3. 성능 최적화
- 환경변수 사용:
.env
파일 대신 시스템 환경변수 사용 권장 - 절대 경로 사용: 상대 경로 대신 절대 경로 사용
- uv 사용:
uv run
을 사용하여 가상환경 자동 관리 - 의존성 캐싱:
uv
의 빠른 의존성 해결 및 캐싱 활용
🐛 오류 처리
모든 함수는 success
필드를 통해 성공/실패를 나타냅니다:
🤝 기여
버그 리포트나 기능 요청은 GitHub Issues를 통해 제출해주세요.
🚀 주요 사용 사례
1. 데이터 마이그레이션
- 기존 데이터베이스의 PII를 안전하게 암호화하여 새 시스템으로 이전
- FPE를 통한 스키마 변경 없이 암호화 적용
2. 개발/테스트 환경
- 프로덕션 데이터의 PII를 익명화하여 테스트 데이터로 활용
- 개발자들이 실제 데이터 없이도 테스트 가능
3. 데이터 분석
- PII를 암호화한 상태에서도 검색 및 분석 가능
- 결정론적 암호화를 통한 그룹핑 및 집계
4. 규정 준수
- GDPR, 개인정보보호법 등 규정에 따른 PII 보호
- 감사 추적을 위한 암호화 로그 관리
MCP PII Tools - 고정밀 개인정보 탐지, 익명화, 암호화 및 복호화 솔루션
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
Enables high-precision detection, anonymization, encryption and decryption of personally identifiable information (PII) in text using GPT-4o-based detection and advanced cryptographic methods. Supports both deterministic encryption for searchable data and format-preserving encryption for structured identifiers.