Librarian MCP

An MCP server that lets an AI client browse, search and read files you mount into its Docker container, reached remotely through a tunnel.

Mount a folder on /data, start the container, and it serves that folder over MCP (Streamable HTTP with a bearer token). The image bundles cloudflared and opens the tunnel itself, so a single docker run gives you a public HTTPS endpoint.

Tools

Clients see the mounted folder as /, so /reports/q3.csv is /data/reports/q3.csv in the container. Paths are resolved like a chroot: .. stops at that root, and symlinks, absolute or relative, are followed inside the mounted folder, never outside it.

Related MCP server: filezop

Quick start

docker build -t librarian-mcp .

# Serve a host folder, read-only
docker run -d --name librarian -v /path/to/files:/data:ro librarian-mcp
docker logs -f librarian

The logs print everything a client needs:

Librarian MCP is reachable at:
  URL:   https://<random-words>.trycloudflare.com/mcp
  Token: 3f1c…  (generated, set MCP_TOKEN to choose your own)

  Claude Code:
  claude mcp add --transport http librarian https://<random-words>.trycloudflare.com/mcp --header "Authorization: Bearer 3f1c…"

  Claude Desktop / claude.ai:
  Settings > Connectors > Add custom connector, URL https://<random-words>.trycloudflare.com/mcp
  then paste the token on the authorization page that opens.

Mount with :ro unless you also set WRITE_ENABLED=true. A named Docker volume works the same way (-v my-volume:/data).

The same setup as a compose file is in examples/docker-compose.yml.

Tunnel modes

• Quick tunnel (default): no Cloudflare account needed. The URL is random and changes on every restart, and Cloudflare gives no uptime guarantee, so it is meant for ad hoc access.

• Named tunnel: create a tunnel in the Cloudflare dashboard (Zero Trust → Networks → Tunnels), add a public hostname pointing to http://localhost:8787, and pass its token as CLOUDFLARE_TUNNEL_TOKEN. The endpoint is then https://<your-hostname>/mcp, stable across restarts, and you can put Cloudflare Access in front of it.

• No tunnel: TUNNEL=none serves on 0.0.0.0:8787 only, for use with -p or your own tunnel (ngrok, Tailscale, ssh -R).

When a tunnel is on, the server listens on 127.0.0.1 only, so the tunnel is the only way in. If cloudflared stops, the container exits so its restart policy can bring both back.

Without Docker, npm run build && ROOT_DIR=/path/to/files MCP_TOKEN=… node dist/index.js serves a local folder (add --stdio for a local stdio client).

Client configuration

There are two ways to authenticate, and both use the same MCP_TOKEN:

• Bearer token, for clients that let you set a header (Claude Code, most MCP configs).

• OAuth, for Claude Desktop and claude.ai custom connectors, which only support OAuth. Add a custom connector with the /mcp URL and no client ID or secret. Claude identifies itself with its published client ID (a Client ID Metadata Document URL, which the server fetches and checks) or registers itself dynamically, then opens an authorization page served by Librarian MCP, and you paste MCP_TOKEN there once. Claude then gets its own access token (valid one hour) and refresh token (valid 30 days).

OAuth needs the server's public URL. It is detected automatically with a quick tunnel; with a named tunnel or your own tunnel, set PUBLIC_URL=https://<your-hostname>. Client registrations and tokens are encrypted with a key derived from MCP_TOKEN rather than stored, so they survive restarts, and changing MCP_TOKEN revokes all of them. With a quick tunnel the URL changes on every restart, so the connector has to be added again. The authorization page shows the host a published client ID comes from (for example claude.ai), since the client name itself is self-declared.

{
  "mcpServers": {
    "librarian": {
      "type": "http",
      "url": "https://<your-tunnel>/mcp",
      "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
    }
  }
}

With Claude Code: claude mcp add --transport http librarian https://<your-tunnel>/mcp --header "Authorization: Bearer <MCP_TOKEN>".

Configuration

GET /healthz answers without auth, for tunnel and container health checks.

Security

A quick tunnel makes the server reachable from the whole internet, protected only by the token (directly, or through the OAuth authorization page, which locks for a minute after 5 wrong tokens), and the URL shows up in your container logs. Anyone holding the token can read every file in the mounted folder. Keep the server read-only unless you need writes, use a long random token, and prefer a tunnel that adds its own access control (Cloudflare Access, Tailscale). To read client ID metadata documents the server makes outbound HTTPS requests to the URL a client presents; it refuses non-public addresses, redirects, documents over 5 KB and slow hosts, and caches results for five minutes. Symlinks are re-resolved on each call, but something that swaps a path component for a symlink between resolution and use can race the check, so do not mount a folder that untrusted processes write to while it is being served.

Development

npm install
npm test          # vitest
npm run typecheck
npm run dev       # tsx src/index.ts, needs MCP_TOKEN or MCP_ALLOW_NO_AUTH=true

Releases

Every push to main runs semantic-release once CI is green. It reads the commits since the last tag, so commit messages must follow Conventional Commits (fix: makes a patch, feat: a minor, feat!: or a BREAKING CHANGE: footer a major; chore:, docs:, ci: and the like release nothing). Pull requests run commitlint to catch bad messages.

A release creates the vX.Y.Z tag and GitHub release, commits CHANGELOG.md, and pushes a multi-arch image (amd64, arm64) to the GitHub Container Registry, so you can skip the build:

docker run -d --name librarian -v /path/to/files:/data:ro ghcr.io/pierrickrouxel/librarian-mcp:latest

Tags: X.Y.Z, X.Y, X and latest. Nothing is published to npm, and package.json carries no version: the tag is the source of truth, and the image passes it to the server through LIBRARIAN_VERSION (local builds report 0.0.0-dev).