# balmas-mcp

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

[![npm](https://img.shields.io/npm/v/balmas-mcp)](https://www.npmjs.com/package/balmas-mcp)
[![license](https://img.shields.io/badge/license-MIT-3DDC97)](./LICENSE)

![balmas-mcp demo: the agent reads a contract and sees PERSON_001 instead of real names](./demo.svg)

## 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)