Log inSubmit server
Balmas MCP logo

Balmas MCP

Reads allowlisted local files through MCP, anonymizes sensitive data locally, and restores non-secret values in agent output.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Balmas MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "balmas-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "balmas-mcp"
      ],
      "env": {
        "BALMAS_API_KEY": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

We couldn’t confirm it starts correctly

The install command installed and started the server, which then stopped for configuration (such as an API key) that our sandbox does not have — expected for servers that connect to your account.

npx -y balmas-mcp

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 4d ago.

Overview

The balmas-mcp MCP server gives agents read-only access to allowlisted local folders while replacing detected personal data and secrets with consistent tokens. It exposes file listing, anonymized file reading, and session-scoped restoration tools over a standard stdio MCP configuration. File contents, paths, and replacement maps remain on the machine; only metering counters leave it. Reach for it when an agent needs document context without receiving the original sensitive values.

Use cases

  • Let agents analyze contracts without exposing original names or identifiers
  • Restrict document access to one or more approved project folders
  • Restore non-secret placeholders in an agent's final response
  • Inspect local spreadsheets and PDFs through a read-only interface

Key features

  • Allowlisted folder access with realpath enforcement
  • Local anonymization with consistent replacement tokens
  • Secret detection for keys, JWTs, credentials, and private keys
  • Read-only MCP tools for file metadata and cleaned content
  • Session-scoped restoration of eligible values
  • Support for text documents, office files, and text-layer PDFs

Tools3

What Balmas MCP lets your agent do. Expand a tool for its parameters.

Self-reported~48 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

5/5 checks healthy over the last 45d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 16d ago via OSV.dev · balmas-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

npm downloads209Package downloads in the last 30 days.
Last commit1mo agoMost recent push to the default branch.
Install checkRunsOur sandbox started it; it then asked for an API key or config.
Tools exposed3Callable tools this server registers over MCP.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How Balmas MCP works

What the balmas-mcp MCP server does

The balmas-mcp MCP server places a privacy gateway between an MCP client and selected local folders. Agents can inspect file metadata and request supported documents, but they receive cleaned text rather than the original content. The server is read-only and does not expose tools for creating, editing, or deleting files.

Folder access is restricted to paths supplied when the process starts. Realpath checks enforce that boundary, so the agent cannot use the gateway to reach unrelated locations. This design is intended for granting an agent access to a dedicated working area instead of giving it raw filesystem access at the same time.

How it works

When a file is read, processing occurs in the local process before the response is returned to the agent. Detected names, identification numbers, phone numbers, email addresses, companies, monetary amounts, and similar data are replaced with stable placeholders such as PERSON_001 or ID_001. Consistent replacements across files let the agent reason about the same person or value without seeing the original.

The detector also handles several classes of secrets, including API keys, JWTs, private-key blocks, password: values, and credentials found in .env files. Secrets are represented as SECRET_001 and are not restored by restore_text. Detection uses deterministic patterns, lexicons, and checksums, including support for Israeli IDs, Hebrew, and English.

The restore_text tool maps eligible tokens in the agent's final response back to original values using the current session's replacement map. File contents, filenames, paths, and that map do not leave the machine. The service receives metering information consisting of file type and item counts, and each file read counts toward the account's document quota.

Setup and configuration

Install and run the package through an MCP client's stdio configuration. The command requires one or more allowed folders as positional arguments and accepts --level with standard, strict, or maximum; strict is the default. Set BALMAS_API_KEY to the key created through a BALMAS AI account.

A typical configuration uses npx with balmas-mcp, an allowed folder path, and the selected processing level. The README specifically shows Claude Desktop and states that Cursor and other clients use the same general configuration approach.

Tools and capabilities

  • list_files returns names, sizes, and types within allowed folders without returning file contents.
  • read_clean_file returns anonymized text for a supported file.
  • restore_text replaces eligible session tokens in agent output with their original values.

Supported inputs are TXT, CSV, Markdown, DOCX, XLSX, PPTX, and PDFs with a text layer. The balmas-mcp MCP server is suitable for workflows where an agent needs to search or interpret local documents but should not receive raw personal data.

Limitations and notes

The privacy boundary applies only when the agent reads files through the gateway. Do not grant the same agent unrestricted filesystem access alongside it if the gateway is intended to enforce minimization.

Detection is deterministic and may miss sensitive information, so review results when the consequences of disclosure are significant. Scanned PDFs without a text layer are not handled by the normal document flow; they require the OCR flow at balmasai.com/clean.

A BALMAS account and API key are required. The balmas-mcp MCP server does not write changes back to source files.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Balmas MCP

balmas-mcp is an MCP server that connects an MCP client to allowlisted local folders and processes their files locally before sharing them. Its main tools list files, return anonymized file text, and restore eligible session tokens in agent output. It is read-only, and secrets are never restored.

Install it through an MCP client's stdio configuration with `npx -y balmas-mcp`. Provide one or more allowed folders as positional arguments, set `BALMAS_API_KEY`, and optionally choose `--level standard`, `strict`, or `maximum`.

Yes, balmas-mcp works with Cursor using the same general MCP configuration approach shown for Claude Desktop. Configure the stdio command, pass the allowed folder paths, select an optional processing level, and provide `BALMAS_API_KEY`.

balmas-mcp supports TXT, CSV, Markdown, DOCX, XLSX, PPTX, and PDFs with a text layer. Scanned PDFs without text require the separate OCR flow referenced in the README.

No, balmas-mcp is read-only and exposes no write tools. It returns cleaned content to the agent, while `restore_text` only substitutes eligible session tokens in output and does not write restored values back to source files.

Related MCP servers

All in File Systems All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewBalmas MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/balmas-mcp?style=directory)](https://allmcps.com/mcp/balmas-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/balmas-mcp"><img src="https://allmcps.com/api/badge/balmas-mcp?style=directory" alt="Balmas MCP on AllMCPs" /></a>