phi-guard-mcp

MCP server and CLI for detecting, redacting, and auditing PHI before medical text is sent to AI agents.

phi-guard-mcp is healthcare AI safety infrastructure, not a clinical product. It is a local, rule-based guardrail that helps developers identify PHI-like identifiers in plain text, redact them with stable placeholders, and produce audit-friendly JSON before content reaches an AI agent or MCP workflow.

Proof points for maintainers:

• Synthetic benchmark with exact-match PHI finding evaluation.
• Safe Harbor mapping audit fields for review workflows.
• CI privacy gate that blocks PHI-like identifiers in maintained source and docs.
• CLI, Python API, and MCP stdio tools sharing one stable JSON result model.

Important scope limits:

• Not for diagnosis, treatment, triage, medical advice, or medication recommendations.
• Not a HIPAA compliance guarantee and not a substitute for legal, privacy, or security review.
• Not an FDA-regulated clinical decision support or device software function.
• Do not test with real patient records. The examples in this repo are synthetic.

The project aligns its documentation vocabulary with HHS HIPAA de-identification concepts such as Safe Harbor and Expert Determination, while intentionally avoiding clinical decision support scope. See HHS de-identification guidance, FDA CDS guidance, and FDA device software functions.

Install

Install from the current GitHub release wheel:

python -m pip install https://github.com/charlesree826/phi-guard-mcp/releases/download/v0.1.2/phi_guard_mcp-0.1.2-py3-none-any.whl

For local development:

python -m pip install -e ".[dev]"

PyPI publishing is configured through GitHub Actions trusted publishing and will be enabled after the PyPI package owner creates the matching pending publisher entry for this repository.

Quickstart

Scan a synthetic note:

phi-guard scan examples/synthetic_clinical_note.txt

Redact PHI-like identifiers:

phi-guard redact examples/synthetic_clinical_note.txt --out /tmp/synthetic_redacted.txt

Audit a note:

phi-guard audit examples/synthetic_clinical_note.txt

Validate text before it enters an AI agent:

phi-guard validate examples/synthetic_clean_note.txt

Run the synthetic benchmark:

phi-guard benchmark benchmarks/synthetic/cases --out benchmarks/synthetic-report.json

Run the repository privacy gate:

phi-guard gate --config .phi-guard.toml

All CLI commands output stable JSON for automation.

See docs/demo.md for a complete CLI and MCP transcript.

MCP Server

Run the stdio MCP server:

phi-guard-mcp

Available tools:

• scan_phi(text)
• redact_phi(text, mode="placeholder")
• audit_deidentification(text)
• validate_no_phi(text)

MCP tools return the same finding schema as the CLI, including safe_harbor_identifier.

Example MCP client config:

{
  "mcpServers": {
    "phi-guard": {
      "command": "phi-guard-mcp"
    }
  }
}

Python API

from phi_guard_mcp import audit_text, evaluate_benchmark, redact_text, scan_text, validate_no_phi

result = scan_text("Patient Name: Jordan Rivera, MRN: MRN-48291")
redacted = redact_text("Patient Name: Jordan Rivera, MRN: MRN-48291")
audit = audit_text("Patient Name: Jordan Rivera, MRN: MRN-48291")
validation = validate_no_phi("No identifiers are present in this synthetic note.")
benchmark = evaluate_benchmark("benchmarks/synthetic/cases")

What It Detects

The first release focuses on plain text and common PHI-like identifiers:

• Names in clinical label contexts
• Dates
• Phone numbers
• Email addresses
• Address-like fragments
• Medical record numbers
• Social Security numbers
• URLs and IP addresses
• Medical facility names
• Account, member, policy, and patient ID tokens

This is a deterministic heuristic engine. It favors transparent behavior and repeatable JSON over opaque model judgment.

Safe Harbor mapping is included as a review aid only. It does not make output HIPAA compliant and does not replace Expert Determination or legal review.

Project Docs

• Demo
• Synthetic benchmark
• Privacy gate
• Safety scope
• Roadmap
• Contributing
• Security policy

Development

python -m compileall -q src tests
python -m pytest -q
ruff check .
phi-guard gate --config .phi-guard.toml
python -m build
twine check dist/*