com.balmasai/balmas-mcp
Agents read cleaned copies of your files: PII replaced with local consistent tokens. Read-only.
Open source Open in the app JSON README (API)
About
Agents read cleaned copies of your files: PII replaced with local consistent tokens. Read-only.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- com.balmasai
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.0
- Last push
- 2026-09-03T17:00:09Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-09-02 16:00:26
- Updated
- 2026-09-03 06:00:19
- Origin id
com.balmasai/balmas-mcp
README
# balmas-mcp
> **Your AI agent reads everything. This gateway hands it redacted copies instead.**
[](https://www.npmjs.com/package/balmas-mcp)
[](./LICENSE)
## 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](https://www.balmasai.com/signup) (10 documents/month free).
2. Create an API key (`bk_...`) at [balmasai.com/app/team](https://www.balmasai.com/app/team).
3. Add to your MCP client config (Claude Desktop shown; Cursor and others are the same idea):
```json
{
"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](https://www.balmasai.com/clean).
---
Built by [BALMAS AI](https://www.balmasai.com) — sensitive data stops here.
Docs: [balmasai.com/mcp](https://www.balmasai.com/mcp)