personal-mcp-bridge

A minimal, read-only bridge that lets an MCP client (or any HTTP caller) browse a few allowlisted local directories safely. Every tool is read-only; there is no write, edit, delete, or execute path anywhere in the surface.

Tools are available through the MCP endpoint POST /mcp, the localhost-only compatibility dispatcher POST /call, and dedicated HTTP endpoints where noted:

• list_roots / GET /roots - list the directories you allowlisted, by alias

• list_files / GET /files - list one allowlisted directory

• read_file / GET /read - read one bounded file inside an allowlisted root

• read_file_range / GET /read-range - read a bounded line range

• tail_file / GET /tail - read the end of a bounded file

• read_multiple_files - read several bounded files through MCP or /call

• get_file_info / GET /file-info - inspect one allowlisted path's metadata

• search / GET /search - search text files under an allowlisted root

It is intentionally small.

read_file, read_multiple_files, and search also understand PDF/DOCX/PPTX/XLSX, citation-prefixed (e.g. [p.3], [Sheet1!2-5]), when you install the optional documents extra (see below). Still read-only, and it degrades gracefully: without the extra, those formats are simply not there.

Read output is character-bounded: read_file/search accept an optional max_chars (capped by BRIDGE_READ_MAX_CHARS) and report the applied limits.

What this is not

This is not a full personal automation layer. It does not run agents, write files, run shell commands, drive a browser, or keep any memory, audit, or cache database. It is an alpha, read-only file bridge with safe defaults. If you came looking for a do-everything assistant runtime, this is the deliberately boring, auditable subset.

Related MCP server: FS Context MCP Server

Safety model in one paragraph

Fail closed. With no roots configured, every request is blocked. Paths are relative-only with no traversal, no drive letters, and no symlink escapes. Common secret, runtime, cache, and generated paths (.env, token/secret/ credential-like files, runtime/settings.json, .git, virtualenvs, node_modules, caches) are excluded from listing, reads, and search. In public/tunnel mode the bridge refuses to start without a strong token, refuses tokens passed in the URL, refuses the generic /call endpoint for any forwarded/remote request, and never emits an absolute local path. See SECURITY.md and THREAT_MODEL.md.

Install

Requires Python 3.10+.

python -m pip install -e .
# or, just install the runtime deps:
python -m pip install starlette uvicorn

To also read PDF/DOCX/PPTX/XLSX files, install the optional documents extra (pypdf, python-docx, python-pptx, openpyxl). The base install stays tiny without it:

python -m pip install -e ".[documents]"

Run the demo (no real files touched)

The demo allowlists only the bundled synthetic demo/mock_data directory and exercises all three tools in-process:

python demo/run_demo.py

You will see list_roots, a file read, a search hit on mock data, and a traversal attempt being refused.

Run the server against your own files

Allowlist one or more directories, then start the bridge on loopback:

export BRIDGE_ROOTS="notes=/path/to/notes;docs=/path/to/work/docs"
python -m personal_mcp_bridge
# serving on http://127.0.0.1:8787

Then:

curl http://127.0.0.1:8787/roots
curl "http://127.0.0.1:8787/files?root=notes&path=."
curl "http://127.0.0.1:8787/read?root=notes&path=welcome.md&max_chars=4000"
curl "http://127.0.0.1:8787/read-range?root=notes&path=welcome.md&start_line=1&line_count=20"
curl "http://127.0.0.1:8787/tail?root=notes&path=welcome.md&last_lines=20"
curl "http://127.0.0.1:8787/file-info?root=notes&path=welcome.md"
curl "http://127.0.0.1:8787/search?root=notes&q=budget&max_chars=4000"

On loopback with no token set, local calls are allowed for convenience. To require a token even locally, set BRIDGE_TOKEN and send Authorization: Bearer <token>.

Runtime limits

Read output uses character caps for schema-facing text; request bodies and search-file scanning use byte caps. Restart the bridge and reconnect/re-register the MCP connector after changing any of these, since some clients cache schemas.

Compatibility aliases BRIDGE_MAX_READ_CHARS, BRIDGE_MAX_READ_BYTES, and BRIDGE_MAX_FILE_BYTES are still accepted for existing setups.

Excluded paths

The bridge skips common secret, runtime, generated-output, dependency, and cache paths during listing and search, and direct reads are refused for those paths. This includes .env and .env.*, token/secret/credential-like filenames, key material, database and log files, runtime/settings.json, .git, virtualenvs, node_modules, common caches, and generated output folders. Do not allowlist a directory if you would not be comfortable with an authorized client reading the ordinary text files inside it.

Exposing it beyond localhost

Don't, unless you mean it. If you put this behind a tunnel, set BRIDGE_PUBLIC_MODE=1 and a strong BRIDGE_TOKEN (>=32 chars). The bridge will refuse to start otherwise. Even then, only the dedicated read-only endpoints are remote-reachable; the generic /call dispatch stays localhost-only.

Status

Alpha. Read-only. Expect rough edges. Issues and PRs welcome.