MCP PII Tools

You can detect, anonymize, encrypt, and decrypt PII for MCP contexts using a focused suite of tools that run locally or via a lightweight client. This MCP PII Tools package provides high-precision PII detection, immediate anonymization, deterministic and format-preserving encryption, and complete decryption, all designed to help you safely process text in Model Context Protocol workflows.

How to use

Connect your MCP client to the local MCP PII Tools server that runs as a standard input/output (stdio) process. You start the server using a lightweight runtime that can manage a long‑running Python script, allowing you to send text for PII detection, anonymization, encryption, or decryption and receive results back in real time. Typical usage patterns include detecting PII in a message, anonymizing identified items, batch processing multiple texts, encrypting specific PII items, and decrypting encrypted content when needed. You can chain together operations to securely prepare data for storage, analysis, or transfer while preserving data formats where required by your database schema.

How to install

Prerequisites you need before installing include Python, a runtime helper for MCP development, and a command runner to manage stdio MCP servers. You will also set up environment variables to control the provider and master key used for encryption and decryption.

Step by step commands you can follow to set up and run MCP PII Tools locally are as follows.

# Prerequisites: Python and a runtime like uv
# Install uv (recommended)
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or install via pip
pip install uv

# Clone the project
git clone https://github.com/your-username/mcp-pii-tools.git
cd mcp-pii-tools

# Install dependencies via uv
uv sync

# Include development dependencies
uv sync --extra dev

# Alternative: install with pip (if you prefer)
pip install langextract[openai] openai python-dotenv cryptography mcp

# Environment and server run example (see next sections for details)

# Start the MCP PII Tools server using uv (stdio mode)
uv run python mcp_pii_tools.py

Additional sections

Configuration and security notes provide essential guidance for keeping data safe while using MCP PII Tools. You will configure a master key for encryption, choose between providers like OpenAI or vLLM, and ensure the server handles encryption locally to minimize data exposure. When using deterministic encryption, the same input yields the same ciphertext and supports search operations. When using FPE, the output maintains the original data format, which helps preserve database schemas.

Environment setup guides show how to prepare the runtime environment, either by an automated setup script, a template file, or manual creation of a .env file. It is important to set the following variables to enable encryption and model access: PII_MASTER_KEY, PII_PROVIDER, OPENAI_API_KEY (or VLLM-related keys if you opt for vLLM), and PII_MODEL_ID. These configurations keep encryption keys separate from the code and allow you to switch providers as needed.

Examples demonstrate common workflows such as detecting PII, anonymizing text, batch processing multiple messages, and encrypting or decrypting individual items or entire texts. Use these patterns to integrate MCP PII Tools into your own pipelines or testing scripts.

Troubleshooting tips cover common issues like server connection failures, missing modules, and environment variable problems. If your tooling cannot locate dependencies, verify the runtime path to uv, ensure dependencies are installed, and confirm that environment variables are correctly exported or loaded.

Available tools

detect_pii

Detects PII items within text, returning item types, positions, and confidence scores.

process_text

Detects PII and applies anonymization to produce text with PII placeholders.

batch_process

Processes multiple texts in a single run and aggregates results.

anonymize_text

Replaces PII items in text with standardized placeholders based on detected items.

encrypt_pii_item

Encrypts a single PII value with a specified type using deterministic or FPE methods.

decrypt_pii_item

Decrypts a previously encrypted PII value based on its type.

encrypt_text_pii

Encrypts all PII items found within a text, returning the encrypted text and a map of encrypted items.

decrypt_text_pii

Decrypts a text containing encrypted PII items using the provided mapping.