DB Results Anonymizer

Do AI agents really need access to your real data to help you debug a database or code?

MCP DB Results Anonymizer is a Python MCP Server that acts as an anonymizing proxy between an AI agent (Claude, GPT, etc.) and databases (PostgreSQL, MySQL, SQL Server + MongoDB).

The agent never sees real data or connection credentials.

┌──────────────┐                                                        
│              │         ┌─────────────────────────────────────────────┐
│   AI Agent   │         │                                             │     ┌──────────────┐
│  (Claude,    │         │          MCP-DB-RESULTS-ANONYMIZER          │┌───►│  PostgreSQL  │
│   Codex...)  │         │                                             ││    └──────────────┘
│              │         │  1. Receives the agent's query              ││    ┌──────────────┐
│  NEVER sees  │         │  2. Executes the query on the DB            │├───►│    MySQL     │
│  the real    │         │  3. Detects PII columns (schema+regex)      ││    └──────────────┘
│  data        │◄──MCP──►│  4. Pseudonymizes (Faker + seed hash)       ││    ┌──────────────┐
│              │         │  5. Returns faked data                      │├───►│  SQL Server  │
│  NEVER knows │         │                                             ││    └──────────────┘
│  the         │         │  Credentials stored server-side             ││    ┌──────────────┐
│  credentials │         │  Consistent mapping in local SQLite         │└───►│   MongoDB    │
│              │         │                                             │     └──────────────┘
│              │         └─────────────────────────────────────────────┘
└──────────────┘                                │
                                                ▼
                                        ┌──────────────┐
                                        │ Local SQLite │
                                        │ (hashed      │
                                        │  mappings)   │
                                        └──────────────┘

Why?

When an AI agent queries a database, the entire result passes through the AI provider's servers - names, emails, phone numbers, addresses, connection credentials.

No existing solution addresses this problem end-to-end via the MCP protocol. Alternatives (mcp-presidio, anonymize.dev) anonymize after the agent has already seen the data. Here, the agent has no direct access to the DB: it must go through the MCP server, which anonymizes before returning the results.

The MCP is the wall (security by design). The project also provides coding-agent hooks (Claude Code, Codex, OpenCode, Cursor) as an additional safety net - see docs/SECURITY.md.

The flow from the agent's perspective

1. The agent sends the SQL query to the MCP proxy
2. The proxy executes the query on the real database
3. The proxy detects columns containing personal data (PII) - see docs/DETECTION.md
4. It replaces real values with pseudonyms
5. It returns only the anonymized result to the agent

The agent never sees the real data. Real names, real salaries, etc. never leave the proxy.

Why send results to the agent at all? Because its role is to help analyze and interpret results - spotting duplicates, anomalies, reformulating data. For that, it needs to see the structure and content of the result. Without the data, it could only fix SQL syntax without ever verifying that the result matches what the user is looking for.

The anonymizer is the compromise: the agent receives data that is realistic in structure (correct columns, correct row count, correct types) but fake in content for anything sensitive. This lets it help concretely without exposing personal data.

Designed for / Not designed for

What the MCP IS designed for

What the MCP is NOT designed for

In short: the MCP answers "why does this query fail?" and "is the data structure correct?", not "what does the data say?".

Architecture

The MCP server is published on Docker Hub: dnjfr/mcp-db-results-anonymizer.

The interactive installer creates a standalone infrastructure directory that pulls the image from Docker Hub - no local build required.

The MCP server connects to databases via a shared Docker network (mcp-db-results-anonymizer-network). Databases are managed separately - the MCP does not bundle them.

Prerequisites: Docker + Docker Compose.

Installation

git clone https://github.com/dnjfr/mcp-db-results-anonymizer.git
cd mcp-db-results-anonymizer
bash install.sh

The installer creates a directory alongside the project, separate from the source code:

projects/
├── mcp-db-results-anonymizer/      ← source code (this repo)
└── db-results-anonymizer-infra/    ← created by the installer

It guides you step by step:

1. Choose the directory name (default: db-results-anonymizer-infra)
2. Configure credentials (auto-generation available)
3. Start the infrastructure (PostgreSQL + MongoDB + MCP server)
4. Choose which demo databases to import
5. Connect your coding agent (Claude Code, Codex, OpenCode, or Cursor) - MCP registration + security hooks are installed automatically

# Your docker-compose.yml
services:
  postgres:
    image: postgres:16
    container_name: mcp_postgres
    networks:
      - mcp-db-results-anonymizer-network

networks:
  mcp-db-results-anonymizer-network:
    external: true

databases:
  my_database:
    type: postgresql
    host: mcp_postgres          # container name
    port: 5432
    user: ${POSTGRES_USER}
    password: ${POSTGRES_PASSWORD}
    database: my_database

Usage Example

A user asks their AI agent to fix a query on demo_employees. The query uses the well-known MySQL column names (emp_no, salary, salaries), but this database uses a different PostgreSQL schema (id, amount, salary) - the agent can't guess, it has to look:

I wrote a query on demo_employees but it crashes.
Can you explain why and fix it?

SELECT e.emp_no, e.first_name, e.last_name, s.salary, t.title
FROM employees e
JOIN salaries s ON e.emp_no = s.emp_no
JOIN titles t ON e.emp_no = t.emp_no
WHERE e.hire_date > '1995-01-01'
  AND t.to_date = '9999-01-01'
  AND s.to_date = '9999-01-01'
ORDER BY s.salary DESC
LIMIT 5;

The agent tries to run it via the MCP. It fails, so it investigates:

I'll check the real schema of demo_employees to identify the errors in your query.

Let me check the schema of the three tables used in your query.

● Called mcp-db-results-anonymizer 3 times

Your query contains 5 errors related to the actual database schema. Here are the details:

┌─────┬───────────────────────────┬──────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────┐
│  #  │  Error in your query      │         Correct value            │                                  Explanation                                  │
├─────┼───────────────────────────┼──────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ 1   │ FROM employees e          │ FROM employees.employee e        │ The table is employees.employee (schema employees, table employee)            │
├─────┼───────────────────────────┼──────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ 2   │ JOIN salaries s           │ JOIN employees.salary s          │ The table is employees.salary (not salaries)                                  │
├─────┼───────────────────────────┼──────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ 3   │ JOIN titles t             │ JOIN employees.title t           │ The table is employees.title (not titles)                                     │
├─────┼───────────────────────────┼──────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ 4   │ e.emp_no / s.emp_no /     │ e.id / s.employee_id /           │ The primary key of employee is id, and the foreign key in salary and title    │
│     │ t.emp_no                  │ t.employee_id                    │ is employee_id                                                                │
├─────┼───────────────────────────┼──────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ 5   │ s.salary                  │ s.amount                         │ The salary column is called amount, not salary                                │
└─────┴───────────────────────────┴──────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────┘

Here is the corrected query:

SELECT e.id, e.first_name, e.last_name, s.amount, t.title
FROM employees.employee e
JOIN employees.salary s ON e.id = s.employee_id
JOIN employees.title t ON e.id = t.employee_id
WHERE e.hire_date > '1995-01-01'
  AND t.to_date = '9999-01-01'
  AND s.to_date = '9999-01-01'
ORDER BY s.amount DESC
LIMIT 5;

Do you want me to run it to verify it works?

If the user accepts:

● Called mcp-db-results-anonymizer

The query works, here are the 5 results:

┌────────┬────────────┬───────────┬─────────┬──────────────┐
│   id   │ first_name │ last_name │ amount  │    title     │
├────────┼────────────┼───────────┼─────────┼──────────────┤
│ 77152  │ Josette    │ Techer    │ 147 777 │ Senior Staff │
├────────┼────────────┼───────────┼─────────┼──────────────┤
│ 96407  │ Lorraine   │ Vaillant  │ 137 374 │ Senior Staff │
├────────┼────────────┼───────────┼─────────┼──────────────┤
│ 458302 │ Camille    │ Fontaine  │ 143 984 │ Staff        │
├────────┼────────────┼───────────┼─────────┼──────────────┤
│ 298341 │ Michelle   │ Dupuy     │ 137 960 │ Staff        │
├────────┼────────────┼───────────┼─────────┼──────────────┤
│ 276755 │ Daniel     │ Merle     │ 111 490 │ Senior Staff │
└────────┴────────────┴───────────┴─────────┴──────────────┘

Warning: Names and monetary amounts are pseudonymized by the database anonymization proxy. 
These are not the actual data-the IDs are reliable, but PII values (such as names and salaries) are 
replaced with realistic fake data on every query.

The agent returns the corrected, working query to the user, and it never saw the real PII.

Note: the MCP proxy only intercepts queries that are actually executed. An AI agent that knows the schema can fix a broken query without ever running it, in which case the MCP does not intervene because no data flows through it. This is not a security issue (no data = nothing to protect), but it means the agent won't verify that the result is correct. To have it validate the result, explicitly ask: "run the corrected query to verify".

MCP Tools

Features

• 4 databases supported: PostgreSQL, MySQL, SQL Server, MongoDB (see docs/CONFIGURATION.md)
• 5-layer PII detection: manual classification, column name patterns, value regex, SQL lineage via sqlglot, value scan fallback
• Deterministic pseudonymization: Faker with seed based on hash(value + session_salt)
• Read-only SQL validation: multi-dialect, fail-closed
• Defense in depth: isolated container + hooks + Bearer token + rate limiting
• Lightweight stack: no ML, no Presidio - pattern matching + Faker + sqlglot

Project Structure

mcp-db-results-anonymizer/          ← source code (Docker Hub: dnjfr/mcp-db-results-anonymizer)
├── src/
│   ├── server.py                   # MCP entry point (FastMCP)
│   ├── config.py                   # YAML config loader
│   ├── database/                   # SQL + MongoDB connectors
│   ├── detection/                  # Pattern matching, SQL lineage, value scan
│   ├── anonymizer/                 # Faker pseudonymization + numeric perturbation
│   ├── storage/                    # Local SQLite (hashed mappings)
│   ├── security/                   # SQL validation, Bearer auth, rate limiting
│   └── tools/                      # MCP tools (query, metadata, fixtures)
├── scripts/                        # Shared security hooks (all agents)
├── infra/                          # Templates for the installer
├── docs/                           # Detailed documentation
├── install.sh                      # Interactive installer
├── config.example.yaml             # Configuration template
├── Dockerfile                      # MCP server image
└── Makefile                        # Docker Hub build/push + MCP registration

Known Limitations

• Person names: if an uncommon first name escapes the value scan, it passes through in plain text
• MongoDB aggregate: computed fields absent from the original schema are not anonymized
• PII in the query: WHERE email = '[email protected]' - the email is transmitted in the query itself
• No native TLS: place a reverse proxy in front for HTTPS (see docs/REVERSE_PROXY_HELP.md)

Documentation

License

Apache License 2.0