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 (every plan works — free includes 10 documents/month).
2. Create an API key (bk_...) at balmasai.com/app/team.
3. Add the server to your client config:

{
  "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).

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 — sensitive data stops here.