PII Scanner

Finding SINs and card numbers without showing them to the model

A local scanner for Canadian SINs and credit card numbers, exposed to Claude as an MCP server. The model can ask where sensitive data lives, but every value it gets back is already masked. The raw numbers never leave the server.

Year
2026
Category
AI, Security
Stack
PythonFastMCPModel Context ProtocolClaude Agent SDKpytestuvGitHub Actions
PII Scanner

PII Scanner answers one question: which of these files hold Social Insurance Numbers or credit card numbers? It lets Claude ask that question without ever seeing a single real number. The model gets file paths, line numbers and values like XXX-XXX-544. Nothing more.

The one rule

File contents and raw matches never leave the server. That rule is enforced in code, not in a prompt: a model can be talked out of an instruction, but it can't be talked into data it was never sent. Every finding is masked at the moment it's created, and the Finding type has no field for the raw value at all: data I never store can't leak.

pii-scanner architectureRaw data stays insideYouask a questionAgent · ask.pyno built-in toolsClaudesees masked values onlyMCP serverserver.py · 2 toolsScanner + detectorsLuhn · prefixes · maskFiles on diskraw SINs, cardsstdio · masked findings only
Everything that crosses out of the dashed box is already masked. The agent has no tools of its own, so the scanner is the only way in.

Telling a SIN from a phone number

Nine digits can be a SIN, a phone number, or an order ID. The detectors don't trust the regex alone: SINs and credit cards both carry a Luhn checksum, so a match that fails it is dropped. Cards also have to start with a real Visa, Mastercard or Amex prefix, and SINs can't start with 0 or 8. A card number is matched first, so its digits can't be reported a second time as a SIN.

How one line becomes a findingLine of textfrom scan_fileRegex matchSIN or card shapeLuhn checkchecksum must passPrefix rulescard brand, SIN startMask + rankXXX-XXX-544 · highDroppedphone, order and invoice numbers that fail a check
Each line runs through the same short chain. A match only becomes a finding if every check passes.

Nothing that passes is thrown away, but not everything is equally likely. Each finding gets a confidence: high when a keyword like SIN, NAS or card sits on the same line, medium when the number is formatted with spaces or dashes, and low for bare digits that might be an invoice number. The agent leads with the high ones.

An MCP server with two tools

  • scan_folder walks a folder and returns a summary (files scanned, files flagged, totals by kind and confidence) plus a report per flagged file. scan_file does the same for one file.
  • Two outcome-shaped tools instead of ten thin ones means fewer calls and less room for the model to get confused.
  • It runs over stdio as a local process with no network port, so the data never leaves the machine. Nothing prints to stdout, because on stdio, stdout is the protocol.
  • Every path has to sit inside SCANNER_ALLOWED_ROOT, and the check fails closed: no variable set means no scan. Symlinks and ../ escapes are resolved and rejected, which limits the damage if the model is tricked by text it reads.

Locking the agent down

The agent is built on the Claude Agent SDK with every built-in tool removed. With Read or Bash available, it could open employees.csv directly and the whole design would be theatre. It also ignores any other MCP servers on the machine. An --audit flag prints every tool result the model received: exactly what Claude saw, so the claim that no raw number reaches it can be checked by reading the output, not taken on trust.

38
tests across detectors, scanner and server
2
MCP tools, both masked
0
built-in tools on the agent
2
operating systems in CI

Proving it

The test that matters most scans the sample data and asserts that no raw number appears anywhere in the output, in any form. Around it sit tests for every separator style, bad checksums, phone and order numbers that must be ignored, and each way out of the allowed root: an outside path, a ../ escape, an unset variable, a symlink. CI runs the whole suite on Linux and Windows with a locked uv environment, so both platforms test the exact same versions.

In Claude Code

The same server plugs straight into Claude Code with one claude mcp add command. Ask it to scan the sample data and it calls scan_folder, then summarizes what came back: six SINs and two card numbers across three files, every one of them masked.

Claude Code's MCP panel showing pii-scanner connected with 2 tools
Claude Code scanning sample_data with pii-scanner and listing only masked SINs and card numbers