Balmas MCP server

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

with realpath checks, not honor rules.

1. You allowlist folders. The agent can't reach anything else — enforced

companies and amounts become consistent tokens (PERSON001, ID001) 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 SECRET001 at every level — and are never written back by restoretext. 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.

1. Every read is anonymized locally. Names, ID numbers, phones, emails,

agent's final output back to the original values — locally.

1. The answer comes back real. restore_text maps the tokens in the

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

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

Privacy model

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

instead of raw filesystem access, not alongside.

• The gateway helps only when the agent reads files through it — grant it

the stakes demand it.

• Detection is deterministic: excellent, not clairvoyant. Review output where

balmasai.com/clean.

• Scanned PDFs (no text layer) need the OCR flow at

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