English Français العربية

com.balmasai/balmas-mcp

Official registry Security

Agents read cleaned copies of your files: PII replaced with local consistent tokens. Read-only.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package balmas-mcp
Claude Code 
claude mcp add balmas-mcp -e 'BALMAS_API_KEY=<your balmas_api_key>' -- npx -y balmas-mcp@0.3.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "balmas-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "balmas-mcp@0.3.0"
            ],
            "env": {
                "BALMAS_API_KEY": "<your balmas_api_key>"
            }
        }
    }
}

Environment variables

  • BALMAS_API_KEY required secret BALMAS API key (bk_...) - free at balmasai.com/app/team

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. balmas-mcp
  2. Why
  3. How it works
  4. Quickstart
  5. Tools
  6. Privacy model
  7. Honest limits

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

ToolWhat the agent gets
list_filesNames, sizes, types inside allowed folders — never contents
read_clean_fileThe file's text after local anonymization
restore_textReal 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 contentsNever
File names / pathsNever
The replacement mapNever
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

Frequently asked questions

What is com.balmasai/balmas-mcp?

Agents read cleaned copies of your files: PII replaced with local consistent tokens. Read-only.

How do I install com.balmasai/balmas-mcp?

It runs on your machine. In Claude Code: claude mcp add balmas-mcp -e 'BALMAS_API_KEY=<your balmas_api_key>' -- npx -y balmas-mcp@0.3.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does com.balmasai/balmas-mcp need an API key?

Yes. It expects BALMAS_API_KEY, which you set in its configuration.

Is com.balmasai/balmas-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains com.balmasai/balmas-mcp?

It is published by YaakovTzedek. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.