balmas-mcp

Your AI agent reads everything. This gateway hands it redacted copies instead.

Why

AI agents are getting file access — and they over-read. Israel's Privacy Protection Authority put it bluntly in its guidance on AI agents: an email-sorting agent can analyze 15 years of correspondence for a 2-year task, infer your health and finances along the way, and leak what it learned. Their recommendation: strict permission minimization — read-only, dedicated folders, minimum necessary data.

balmas-mcp turns that advice into code, and goes one step further: it minimizes not just which files the agent reads, but what's inside them.

How it works

1. You allowlist folders. The agent can't reach anything else — enforced with realpath checks, not honor rules.
2. Every read is anonymized locally. Names, ID numbers, phones, emails, companies and amounts become consistent tokens (PERSON_001, ID_001) before the content is returned. Secrets too: API keys (OpenAI, Anthropic, GitHub, AWS, Stripe, Slack…), JWTs, private-key blocks, password: values and .env credentials become SECRET_001 at every level — and are never written back by restore_text. The same person is PERSON_001 in every file, so the agent's reasoning stays coherent. Detection runs in this process — deterministic patterns, lexicons and checksums (Israeli ID included). Hebrew and English.
3. The answer comes back real. restore_text maps the tokens in the agent's final output back to the original values — locally.

Read-only by design: the server exposes no write tools at all.

Quickstart

1. Create a free account at balmasai.com/signup (10 documents/month free).
2. Create an API key (bk_...) at balmasai.com/app/team.
3. Add to your MCP client config (Claude Desktop shown; Cursor and others are the same idea):

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

Options: allowed folders as positional args (required, one or more) · --level standard|strict|maximum (default strict).

Tools

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

Supported inputs: txt csv md docx xlsx pptx pdf (text layer).

Privacy model

	Leaves your machine?
File contents	Never
File names / paths	Never
The replacement map	Never
Metering counters (file type + item counts)	Yes — that's all

Each file read counts as one document against your account's monthly quota (free 10 / PRO 200 / TEAM 1,000). Full processing happens in this local process.

Honest limits

• The gateway helps only when the agent reads files through it — grant it instead of raw filesystem access, not alongside.
• Detection is deterministic: excellent, not clairvoyant. Review output where the stakes demand it.
• Scanned PDFs (no text layer) need the OCR flow at balmasai.com/clean.

---

Built by BALMAS AI — sensitive data stops here. Docs: balmasai.com/mcp