Skip to main content
Glama

MCP PII Tools

by czangyeob

MCP PII Tools

Model Context Protocol (MCP)을 위한 PII(개인식별정보) 탐지, 익명화, 암호화 및 복호화 도구입니다.

🚀 주요 기능

  • 고정밀 PII 탐지: GPT-4o 기반 langextract를 사용한 정확한 PII 탐지
  • 다양한 PII 유형 지원: 이름, 이메일, 전화번호, 여권번호, 주소, 신용카드번호, 주민등록번호 등
  • 실시간 익명화: 탐지된 PII를 즉시 익명화 처리
  • 고급 암호화: 결정론적 암호화(검색 가능) 및 FPE(형식 유지 암호화) 지원
  • 완전한 복호화: 암호화된 텍스트를 원본으로 복원
  • 일괄 처리: 여러 텍스트를 효율적으로 처리
  • MCP 호환: Model Context Protocol 표준을 준수

📦 설치 요구사항

1. uv 설치 (권장)

# uv 설치 (macOS/Linux) curl -LsSf https://astral.sh/uv/install.sh | sh # 또는 pip로 설치 pip install uv

2. 프로젝트 설치

# 저장소 클론 git clone https://github.com/your-username/mcp-pii-tools.git cd mcp-pii-tools # 의존성 설치 uv sync # 개발 의존성 포함 설치 uv sync --extra dev

3. pip 사용 (대안)

pip install langextract[openai] openai python-dotenv cryptography mcp

🔐 암호화 방식

결정론적 암호화 (Deterministic Encryption)

  • 용도: 이름, 주소, 이메일
  • 특징: 같은 입력 → 같은 암호문 (검색 가능)
  • 알고리즘: AES-CBC with PBKDF2
  • 출력: Base64 인코딩

FPE (Format Preserving Encryption)

  • 용도: 전화번호, 신용카드번호, 여권번호, 주민등록번호, 은행계좌번호
  • 특징: 원본 형식 유지 (010-1234-5678 → 808-2523-9129)
  • 알고리즘: 컨텍스트 기반 결정론적 변환
  • 출력: 동일한 형식의 암호문

🔧 사용법

1. 기본 PII 탐지

from mcp_pii_tools import mcp_detect_pii result = mcp_detect_pii("김철수 씨의 이메일은 kim@example.com입니다.") print(f"탐지된 PII: {result['count']}개")

2. 텍스트 처리 (탐지 + 익명화)

from mcp_pii_tools import mcp_process_text result = mcp_process_text("Rachel Lim의 전화번호는 010-1234-5678입니다.") print(f"익명화된 텍스트: {result['anonymized_text']}")

3. 일괄 처리

from mcp_pii_tools import mcp_batch_process texts = [ "김철수 씨가 방문했다.", "박지현 님의 이메일은 park@test.com입니다.", "John Smith의 전화번호는 010-9876-5432입니다." ] result = mcp_batch_process(texts) print(f"총 탐지된 PII: {result['total_pii_detected']}개")

4. 익명화 처리

from mcp_pii_tools import mcp_anonymize_text # PII 항목들 pii_items = [ {"type": "이름", "value": "김철수", "start_pos": 0, "end_pos": 3, "confidence": 0.9}, {"type": "전화번호", "value": "010-1234-5678", "start_pos": 10, "end_pos": 23, "confidence": 0.9} ] anonymized = mcp_anonymize_text("김철수 씨의 전화번호는 010-1234-5678입니다.", pii_items) print(anonymized) # "[이름] 씨의 전화번호는 [전화번호]입니다."

5. 개별 PII 항목 암호화

from mcp_pii_tools import mcp_encrypt_pii_item, mcp_decrypt_pii_item # 암호화 encrypt_result = mcp_encrypt_pii_item("김철수", "이름") print(f"암호화: {encrypt_result['encrypted_value']}") # 복호화 decrypt_result = mcp_decrypt_pii_item(encrypt_result['encrypted_value'], "이름") print(f"복호화: {decrypt_result['decrypted_value']}")

6. 텍스트 전체 암호화/복호화

from mcp_pii_tools import mcp_encrypt_text_pii, mcp_decrypt_text_pii # 텍스트 암호화 text = "김철수 씨의 이메일은 kim@example.com이고 전화번호는 010-1234-5678입니다." encrypt_result = mcp_encrypt_text_pii(text) print(f"암호화된 텍스트: {encrypt_result['encrypted_text']}") # 텍스트 복호화 decrypt_result = mcp_decrypt_text_pii( encrypt_result['encrypted_text'], encrypt_result['encrypted_items'] ) print(f"복호화된 텍스트: {decrypt_result['decrypted_text']}")

🛠️ MCP Tools

1. detect_pii

텍스트에서 PII를 탐지합니다.

매개변수:

  • text (string): 분석할 텍스트

반환값:

{ "success": true, "pii_items": [ { "type": "이름", "value": "김철수", "confidence": 0.9, "start_pos": 0, "end_pos": 3 } ], "count": 1, "processing_time": 1.234, "summary": {"이름": 1} }

2. process_text

텍스트에서 PII를 탐지하고 익명화 처리합니다.

매개변수:

  • text (string): 처리할 텍스트

반환값:

{ "success": true, "original_text": "김철수 씨의 이메일은 kim@example.com입니다.", "anonymized_text": "[이름] 씨의 이메일은 [이메일]입니다.", "pii_items": [...], "count": 2, "processing_time": 1.234, "summary": {"이름": 1, "이메일": 1} }

3. batch_process

여러 텍스트를 일괄적으로 처리합니다.

매개변수:

  • texts (array): 처리할 텍스트 리스트

반환값:

{ "success": true, "results": [...], "total_texts": 3, "successful_count": 3, "total_pii_detected": 5, "processing_time": 3.456, "average_time_per_text": 1.152 }

4. anonymize_text

PII 항목들을 사용하여 텍스트를 익명화합니다.

매개변수:

  • text (string): 원본 텍스트
  • pii_items (array): PII 항목들

반환값:

"[이름] 씨의 전화번호는 [전화번호]입니다."

5. encrypt_pii_item

개별 PII 항목을 암호화합니다.

매개변수:

  • pii_value (string): 암호화할 PII 값
  • pii_type (string): PII 유형 (이름, 전화번호, 이메일 등)

반환값:

{ "success": true, "original_value": "김철수", "encrypted_value": "X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q=", "pii_type": "이름", "encryption_method": "deterministic" }

6. decrypt_pii_item

암호화된 PII 항목을 복호화합니다.

매개변수:

  • encrypted_value (string): 복호화할 암호화된 값
  • pii_type (string): PII 유형

반환값:

{ "success": true, "encrypted_value": "X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q=", "decrypted_value": "김철수", "pii_type": "이름", "decryption_method": "deterministic" }

7. encrypt_text_pii

텍스트에서 PII를 탐지하고 모든 PII를 암호화합니다.

매개변수:

  • text (string): 처리할 텍스트

반환값:

{ "success": true, "original_text": "김철수 씨의 이메일은 kim@example.com입니다.", "encrypted_text": "X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q= 씨의 이메일은 Y2F0YWxvZ0BleGFtcGxlLmNvbQ==입니다.", "pii_items": [...], "encrypted_items": { "김철수": "X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q=", "kim@example.com": "Y2F0YWxvZ0BleGFtcGxlLmNvbQ==" }, "count": 2, "processing_time": 1.234, "summary": {"이름": 1, "이메일": 1} }

8. decrypt_text_pii

암호화된 텍스트에서 PII를 복호화합니다.

매개변수:

  • encrypted_text (string): 암호화된 텍스트
  • encrypted_items (object): 원본값 → 암호화값 매핑

반환값:

{ "success": true, "encrypted_text": "X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q= 씨의 이메일은 Y2F0YWxvZ0BleGFtcGxlLmNvbQ==입니다.", "decrypted_text": "김철수 씨의 이메일은 kim@example.com입니다.", "decrypted_items": { "X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q=": "김철수", "Y2F0YWxvZ0BleGFtcGxlLmNvbQ==": "kim@example.com" }, "count": 2, "processing_time": 0.567 }

🎯 지원하는 PII 유형

유형한국어영어예시암호화 방식
이름이름name김철수, Rachel Lim결정론적
이메일이메일emailkim@example.com결정론적
주소주소address서울시 강남구 테헤란로 123결정론적
전화번호전화번호phone010-1234-5678FPE
여권번호여권번호passport_numberM31143886FPE
신용카드번호신용카드번호credit_card4532-1234-5678-9012FPE
주민등록번호주민등록번호ssn123456-1234567FPE
은행계좌번호은행계좌번호bank_account123-456-789012FPE

⚡ 성능 특성

  • 정확도: 100% (GPT-4o 기반)
  • 처리 시간: 평균 1.3초/텍스트 (탐지), 0.1초/텍스트 (암호화/복호화)
  • 지원 언어: 한국어, 영어, 혼합 텍스트
  • 동시 처리: 일괄 처리 지원
  • 암호화 성능: 초당 수천 건 처리 가능

🔒 보안 고려사항

  • PII 탐지: OpenAI API를 통한 텍스트 전송이 발생할 수 있습니다
  • 암호화: 모든 암호화/복호화는 로컬에서 처리됩니다
  • 키 관리: PII_MASTER_KEY 환경변수로 마스터 키 설정 필요
  • 데이터 보호: 암호화된 데이터는 검색 가능하지만 원본 복원 불가능
  • 형식 유지: FPE를 통해 데이터베이스 스키마 변경 없이 암호화 가능

📝 예제 실행

uv 사용 (권장)

# 기본 테스트 (탐지, 익명화, 암호화/복호화) uv run python mcp_pii_tools.py # 사용 예제 (상세한 예제들) uv run python mcp_pii_example.py # 암호화 모듈 단독 테스트 uv run python pii_crypto.py

pip 사용

# 기본 테스트 (탐지, 익명화, 암호화/복호화) python mcp_pii_tools.py # 사용 예제 (상세한 예제들) python mcp_pii_example.py # 암호화 모듈 단독 테스트 python pii_crypto.py

🔧 환경 설정

1. 환경변수 설정

방법 1: 템플릿 파일 사용 (권장)
# 템플릿 파일을 .env로 복사 cp env.template.txt .env # .env 파일을 편집하여 실제 값 입력 nano .env # 또는 vim, code 등
방법 2: 직접 생성
# .env 파일 생성 echo "OPENAI_API_KEY=your_openai_api_key_here" > .env echo "PII_MASTER_KEY=your_secure_master_key_here" >> .env
필수 환경변수
  • OPENAI_API_KEY: OpenAI API 키 (https://platform.openai.com/api-keys)
  • PII_MASTER_KEY: PII 암호화용 마스터 키 (32자 이상 권장)
마스터 키 생성 방법
# OpenSSL 사용 openssl rand -base64 32 # Python 사용 python -c "import secrets; print(secrets.token_urlsafe(32))"

2. MCP 서버 실행

uv 사용 (권장):
# uv로 MCP 서버 실행 uv run python mcp_pii_tools.py # 또는 가상환경 활성화 후 실행 uv shell python mcp_pii_tools.py
pip 사용:
# MCP 서버로 실행 (Claude Desktop 등에서 사용) python mcp_pii_tools.py

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 설정 파일 위치:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows 설정 파일 위치:
%APPDATA%\Claude\claude_desktop_config.json

2. 설정 파일 내용

권장 설정 (uv 사용):
{ "mcpServers": { "mcp-pii-tools": { "command": "/opt/homebrew/bin/uv", "args": ["run", "--directory", "/Users/matthew/Workspace/mcp-pii-tools", "python", "mcp_pii_tools.py"], "env": { "OPENAI_API_KEY": "your_openai_api_key_here", "PII_MASTER_KEY": "your_secure_master_key_here" } } } }
중요한 설정 포인트:
  1. uv 전체 경로 사용: commanduv의 전체 경로를 지정
    • macOS (Homebrew): /opt/homebrew/bin/uv
    • macOS (직접 설치): ~/.cargo/bin/uv
    • Linux: ~/.cargo/bin/uv
  2. 디렉터리 명시: --directory 옵션으로 프로젝트 디렉터리 지정
    • Claude Desktop이 실행될 때 올바른 가상환경을 찾을 수 있도록 함
    • pyproject.toml이 있는 디렉터리를 정확히 지정해야 함
  3. 상대 경로 사용: args에서 스크립트 파일명만 사용
    • --directory로 작업 디렉터리가 설정되므로 상대 경로로 충분
대안 설정 (pip 사용):
{ "mcpServers": { "mcp-pii-tools": { "command": "python", "args": ["/Users/matthew/Workspace/mcp-pii-tools/mcp_pii_tools.py"], "env": { "OPENAI_API_KEY": "your_openai_api_key_here", "PII_MASTER_KEY": "your_secure_master_key_here" } } } }

3. 설정 방법

  1. Claude Desktop 종료
  2. 설정 파일 편집 (위 경로의 JSON 파일)
  3. Claude Desktop 재시작
  4. MCP 서버 연결 확인

4. 사용 예시

Claude Desktop에서 다음과 같이 사용할 수 있습니다:

"이 텍스트에서 개인정보를 찾아서 익명화해줘: 김철수 씨의 이메일은 kim@example.com이고 전화번호는 010-1234-5678입니다."

🖥️ Cursor 설정

1. Cursor MCP 설정

Cursor에서 MCP 서버를 사용하려면 설정을 추가해야 합니다.

설정 파일 위치:
~/.cursor/mcp_settings.json

2. 설정 파일 내용

{ "mcpServers": { "mcp-pii-tools": { "command": "uv", "args": ["run", "python", "/Users/matthew/Workspace/mcp-hello/mcp_pii_tools.py"], "env": { "OPENAI_API_KEY": "your_openai_api_key_here", "PII_MASTER_KEY": "your_secure_master_key_here" } } } }

3. Cursor에서 사용

  1. Cursor 설정 열기 (Cmd/Ctrl + ,)
  2. MCP 설정 추가
  3. Cursor 재시작
  4. MCP 도구 사용

🔧 수동 테스트

1. MCP 서버 직접 테스트

uv 사용 (권장):
# 서버 실행 uv run python mcp_pii_tools.py # 다른 터미널에서 테스트 echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | uv run python mcp_pii_tools.py
pip 사용:
# 서버 실행 python mcp_pii_tools.py # 다른 터미널에서 테스트 echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | python mcp_pii_tools.py

2. 개별 도구 테스트

uv 사용 (권장):
# PII 탐지 테스트 uv run python -c " from mcp_pii_tools import mcp_detect_pii result = mcp_detect_pii('김철수 씨의 이메일은 kim@example.com입니다.') print(result) "
pip 사용:
# PII 탐지 테스트 python -c " from mcp_pii_tools import mcp_detect_pii result = mcp_detect_pii('김철수 씨의 이메일은 kim@example.com입니다.') print(result) "

🚨 문제 해결

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이 실행할 때 올바른 가상환경을 찾지 못함

해결 방법:

  1. uv 전체 경로 사용:
    "command": "/opt/homebrew/bin/uv"
  2. 디렉터리 명시:
    "args": ["run", "--directory", "/Users/matthew/Workspace/mcp-pii-tools", "python", "mcp_pii_tools.py"]
  3. uv 경로 확인:
    which uv # 결과: /opt/homebrew/bin/uv (macOS Homebrew) # 또는: ~/.cargo/bin/uv (직접 설치)
  4. 수동 테스트:
    /opt/homebrew/bin/uv run --directory /Users/matthew/Workspace/mcp-pii-tools python mcp_pii_tools.py

2. 도구가 보이지 않는 경우

  • Claude Desktop 재시작: 설정 변경 후 반드시 재시작
  • 로그 확인: Claude Desktop 로그에서 오류 메시지 확인
  • 설정 파일 문법: JSON 문법이 올바른지 확인

3. 성능 최적화

  • 환경변수 사용: .env 파일 대신 시스템 환경변수 사용 권장
  • 절대 경로 사용: 상대 경로 대신 절대 경로 사용
  • uv 사용: uv run을 사용하여 가상환경 자동 관리
  • 의존성 캐싱: uv의 빠른 의존성 해결 및 캐싱 활용

🐛 오류 처리

모든 함수는 success 필드를 통해 성공/실패를 나타냅니다:

result = mcp_detect_pii("텍스트") if result['success']: print(f"탐지된 PII: {result['count']}개") else: print(f"오류: {result['error']}")

🤝 기여

버그 리포트나 기능 요청은 GitHub Issues를 통해 제출해주세요.

🚀 주요 사용 사례

1. 데이터 마이그레이션

  • 기존 데이터베이스의 PII를 안전하게 암호화하여 새 시스템으로 이전
  • FPE를 통한 스키마 변경 없이 암호화 적용

2. 개발/테스트 환경

  • 프로덕션 데이터의 PII를 익명화하여 테스트 데이터로 활용
  • 개발자들이 실제 데이터 없이도 테스트 가능

3. 데이터 분석

  • PII를 암호화한 상태에서도 검색 및 분석 가능
  • 결정론적 암호화를 통한 그룹핑 및 집계

4. 규정 준수

  • GDPR, 개인정보보호법 등 규정에 따른 PII 보호
  • 감사 추적을 위한 암호화 로그 관리

MCP PII Tools - 고정밀 개인정보 탐지, 익명화, 암호화 및 복호화 솔루션

Deploy Server
-
security - not tested
F
license - not found
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

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.

  1. 🚀 주요 기능
    1. 📦 설치 요구사항
      1. 1. uv 설치 (권장)
      2. 2. 프로젝트 설치
      3. 3. pip 사용 (대안)
    2. 🔐 암호화 방식
      1. 결정론적 암호화 (Deterministic Encryption)
      2. FPE (Format Preserving Encryption)
    3. 🔧 사용법
      1. 1. 기본 PII 탐지
      2. 2. 텍스트 처리 (탐지 + 익명화)
      3. 3. 일괄 처리
      4. 4. 익명화 처리
      5. 5. 개별 PII 항목 암호화
      6. 6. 텍스트 전체 암호화/복호화
    4. 🛠️ MCP Tools
      1. 1. detect_pii
      2. 2. process_text
      3. 3. batch_process
      4. 4. anonymize_text
      5. 5. encrypt_pii_item
      6. 6. decrypt_pii_item
      7. 7. encrypt_text_pii
      8. 8. decrypt_text_pii
    5. 🎯 지원하는 PII 유형
      1. ⚡ 성능 특성
        1. 🔒 보안 고려사항
          1. 📝 예제 실행
            1. uv 사용 (권장)
            2. pip 사용
          2. 🔧 환경 설정
            1. 1. 환경변수 설정
            2. 2. MCP 서버 실행
            3. 3. 사용 가능한 MCP Tools
          3. 🖥️ Claude Desktop 설정
            1. 1. Claude Desktop MCP 설정
            2. 2. 설정 파일 내용
            3. 3. 설정 방법
            4. 4. 사용 예시
          4. 🖥️ Cursor 설정
            1. 1. Cursor MCP 설정
            2. 2. 설정 파일 내용
            3. 3. Cursor에서 사용
          5. 🔧 수동 테스트
            1. 1. MCP 서버 직접 테스트
            2. 2. 개별 도구 테스트
          6. 🚨 문제 해결
            1. 1. MCP 서버 연결 실패
            2. 1.1. 모듈을 찾을 수 없는 오류 (ModuleNotFoundError)
            3. 2. 도구가 보이지 않는 경우
            4. 3. 성능 최적화
          7. 🐛 오류 처리
            1. 🤝 기여
              1. 🚀 주요 사용 사례
                1. 1. 데이터 마이그레이션
                2. 2. 개발/테스트 환경
                3. 3. 데이터 분석
                4. 4. 규정 준수

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/czangyeob/mcp-pii-tools'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server