Skip to main content
Glama
czangyeob

MCP PII Tools

by czangyeob
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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

결정론적

이메일

이메일

email

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 사용 (권장)

# 기본 테스트 (탐지, 익명화, 암호화/복호화)
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: 자동 설정 스크립트 사용 (가장 쉬움)

# 대화형 설정 스크립트 실행
uv run python setup_env.py

방법 2: 템플릿 파일 사용

# 템플릿 파일을 .env로 복사
cp env.template.txt .env

# .env 파일을 편집하여 실제 값 입력
nano .env  # 또는 vim, code 등

방법 3: 직접 생성

OpenAI 사용 시:

# .env 파일 생성
echo "PII_PROVIDER=openai" > .env
echo "OPENAI_API_KEY=your_openai_api_key_here" >> .env
echo "PII_MASTER_KEY=your_secure_master_key_here" >> .env
echo "PII_MODEL_ID=gpt-4o" >> .env

vLLM 사용 시:

# .env 파일 생성
echo "PII_PROVIDER=vllm" > .env
echo "VLLM_API_KEY=your_vllm_api_key_here" >> .env
echo "PII_MASTER_KEY=your_secure_master_key_here" >> .env
echo "PII_MODEL_ID=qwen3-235b-awq" >> .env
echo "VLLM_BASE_URL=https://qwen.smartmind.team/v1" >> .env
echo "VLLM_TIMEOUT=600" >> .env
echo "VLLM_TEMPERATURE=0.0" >> .env
echo "VLLM_MAX_TOKENS=4096" >> .env

필수 환경변수

  • PII_MASTER_KEY: PII 암호화용 마스터 키 (선택사항, 기본값: "pii_master_key_1!smartmind")

Provider별 환경변수

OpenAI 사용 시:

vLLM 사용 시:

  • VLLM_API_KEY: vLLM API 키 (OPENAI_API_KEY와 동일하게 사용 가능)

  • VLLM_BASE_URL: vLLM 서버 URL (기본값: https://qwen.smartmind.team/v1)

  • PII_MODEL_ID: 모델 ID (기본값: qwen3-235b-awq)

  • VLLM_TIMEOUT: 요청 타임아웃 (초, 기본값: 600)

  • VLLM_TEMPERATURE: 온도 (기본값: 0.0)

  • VLLM_MAX_TOKENS: 최대 토큰 수 (기본값: 4096)

마스터 키 생성 방법

# 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"]
    }
  }
}

중요한 설정 포인트:

  1. uv 전체 경로 사용: command에 uv의 전체 경로를 지정

    • 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"]
    }
  }
}

3. 환경변수 설정

중요: API 키와 설정은 JSON 파일이 아닌 환경변수로 관리합니다.

방법 1: 자동 설정 스크립트 사용 (권장)

# 프로젝트 디렉터리에서 실행
uv run python setup_env.py

방법 2: .env 파일 사용

# 템플릿 파일을 .env로 복사
cp env.template.txt .env

# .env 파일을 편집하여 실제 값 입력
nano .env  # 또는 vim, code 등

방법 3: 시스템 환경변수 설정

# macOS/Linux
export OPENAI_API_KEY="your_openai_api_key_here"
export PII_MASTER_KEY="your_secure_master_key_here"

# Windows
set OPENAI_API_KEY=your_openai_api_key_here
set PII_MASTER_KEY=your_secure_master_key_here

4. 설정 완료

  1. Claude Desktop 종료

  2. 환경변수 설정 (위 방법 중 하나 선택)

  3. Claude Desktop 재시작

  4. MCP 서버 연결 확인

5. 사용 예시

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-pii-tools/mcp_pii_tools.py"]
    }
  }
}

3. 환경변수 설정

중요: API 키와 설정은 JSON 파일이 아닌 환경변수로 관리합니다.

방법 1: 자동 설정 스크립트 사용 (권장)

# 프로젝트 디렉터리에서 실행
uv run python setup_env.py

방법 2: .env 파일 사용

# 템플릿 파일을 .env로 복사
cp env.template.txt .env

# .env 파일을 편집하여 실제 값 입력
nano .env  # 또는 vim, code 등

4. Cursor에서 사용

  1. Cursor 설정 열기 (Cmd/Ctrl + ,)

  2. MCP 설정 추가

  3. 환경변수 설정 (위 방법 중 하나 선택)

  4. Cursor 재시작

  5. 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 - 고정밀 개인정보 탐지, 익명화, 암호화 및 복호화 솔루션

Install Server
A
security – no known vulnerabilities
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Appeared in Searches

Latest Blog Posts

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