BALMAS
Agents read cleaned copies of your files: PII replaced with local consistent tokens. Read-only.
Runs on your machine from its package; the steps are below.
What it does
- Reads
- Writes
- High impact
At most: only reads or looks up information.
What it costs
FreeOdel charges nothing per call. The publisher may charge for its own service.
Runs locally over stdio
This server isn't hosted — your MCP client launches it from a package registry. Use one of the commands below, or drop the config into your client (e.g. Claude Desktop).
Run
npx -y balmas-mcp
MCP client config
{
"mcpServers": {
"balmas": {
"command": "npx",
"args": [
"-y",
"balmas-mcp"
]
}
}
}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
- You allowlist folders. The agent can't reach anything else — enforced with realpath checks, not honor rules.
- 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.envcredentials becomeSECRET_001at every level — and are never written back byrestore_text. The same person isPERSON_001in 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. - The answer comes back real.
restore_textmaps 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
- Create a free account at balmasai.com/signup (10 documents/month free).
- Create an API key (
bk_...) at balmasai.com/app/team. - 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
