# balmas-mcp — anonymization gateway for AI agents

Give your AI agent **cleaned copies** of your documents instead of the real
thing. Every file the agent reads through this MCP server passes through
BALMAS's deterministic detection engine **locally, in this process**: names,
Israeli ID numbers, phones, emails, companies, amounts and more are replaced
with consistent tokens (`PERSON_001`, `ID_001`…) before any content is
returned. Hebrew and English.

This is the technical enforcement of the permission-minimization approach
recommended by Israel's Privacy Protection Authority for AI agents:

- **Read-only by design** — the server exposes no write tools at all.
- **Folder allowlist** — the agent can only reach folders you list explicitly.
- **Content minimization** — not just *which* files, but *what's inside* them.
- **Secrets covered** — API keys, JWTs, private-key blocks, `password:` values
  and `.env` credentials become `SECRET_001` at every level, and are never
  restored back into free text.
- **Zero cloud** — detection runs in this local process; nothing is uploaded.
- **Session-consistent tokens** — the same person is `PERSON_001` in every
  file, so the agent's reasoning stays coherent across documents.
- **Round-trip** — `restore_text` puts the real values back into the agent's
  final answer, locally.

## Install (Claude Desktop example)

1. Create a free account at [balmasai.com/signup](https://www.balmasai.com/signup)
   (every plan works — free includes 10 documents/month).
2. Create an API key (`bk_...`) at [balmasai.com/app/team](https://www.balmasai.com/app/team).
3. Add the server to your client config:

```json
{
  "mcpServers": {
    "balmas": {
      "command": "npx",
      "args": ["-y", "balmas-mcp", "/Users/me/Documents/work", "--level", "strict"],
      "env": { "BALMAS_API_KEY": "bk_..." }
    }
  }
}
```

Any MCP-compatible client (Claude Desktop, Cursor, etc.) works the same way:
point it at `balmas-mcp` with the folders you allow.

## Options

- Positional arguments: allowed folders (at least one, required).
- `--level standard|strict|maximum` — which categories are replaced
  (default `strict`: personal + financial + organizational data).
- `--key bk_...` — BALMAS API key (or the `BALMAS_API_KEY` env var, required).

## Metering & privacy

Each file the agent reads counts as one document against your account's
monthly quota (free 10 / PRO 200 / TEAM 1,000 — resets on the 1st). Metering
sends **anonymous counters only** (file type, item counts): never file
contents, never file names, never paths. All detection and replacement run in
this local process.

## Tools

| Tool | What it does |
|---|---|
| `list_files` | Names, sizes and types inside allowed folders — never contents |
| `read_clean_file` | The file's text after local anonymization |
| `restore_text` | Real values back into the agent's output (session tokens only) |

Supported inputs: `txt`, `csv`, `md`, `docx`, `xlsx`, `pptx`, `pdf` (text
layer; scanned PDFs → use the OCR flow at [balmasai.com/clean](https://www.balmasai.com/clean)).

## Honest limits

Detection is deterministic (patterns + lexicons + checksums), excellent but
not clairvoyant — review output where the stakes demand it. And the gateway
only helps if the agent reads files **through it**: grant it *instead of* raw
filesystem access, not alongside.

Built by [BALMAS AI](https://www.balmasai.com) — sensitive data stops here.