Skip to content
Back to search

dirmcp

MCP server that gives remote AI clients shell-like access to one directory, using real Unix tools from an allowlist

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/dafrick/dirmcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/dafrick/dirmcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dafrick--dirmcp/badge.svg)](/listings/dafrick--dirmcp)

HTML

<a href="/listings/dafrick--dirmcp"><img src="/api/listings/dafrick--dirmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install Nix ([nixos.org/download](https://nixos.org/download)) and enable flakes. 2. Enter the dev shell: `nix develop`. It provides the tools (Go, `openspec`, `gh`) and installs the git hooks. 3. Run all checks:

   nix flake check                                     # pre-commit hooks
   pre-commit run --all-files --hook-stage pre-push    # pre-push hooks

Then read [CONTRIBUTING.md](CONTRIBUTING.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 105 lines
  1. # dirmcp
  2. An [MCP](https://modelcontextprotocol.io) server that gives a remote AI client (for example a claude.ai custom connector) shell-like access to **one directory**, using the real Unix tools from an allowlist.
  3. Status: usable. Server (`sh`, `more`, `create`) and NixOS module with hardened instances.
  4. > **Warning.** dirmcp gives whoever holds its token remote access to the directory it serves, with everything the allowed tools can do there. Read [Deploying securely](#deploying-securely) before you expose it.
  5. ## What the client gets
  6. | Tool | What it does |
  7. |---|---|
  8. | `sh` | Runs a command line in the directory: pipes, `for` loops, `$( )`, redirections. Only these programs run: `awk basename cat cmp comm cp cut date df diff dirname du file find fmt fold gawk grep head join ls md5sum mkdir mv nl paste readlink realpath rg sed sha256sum sort stat tac tail touch tr tree uniq wc`, plus a built-in `rm` that moves to `.trash/`. Most options work; options that run other programs or write elsewhere are refused (`find -exec`, `rg --pre`, `sort --compress-program`, …), and `sed`/`gawk` always run with `--sandbox`. No shells, `xargs` or `env`. |
  9. | `more` | Next part of an answer that was cut at 30 KB or still running after 15 s. Output is kept in RAM for 10 minutes. |
  10. | `create` | Only with `--create-in DIR`: makes a new file below `DIR`, never overwrites. |
  11. Every started program gets its own root in new user, mount and network namespaces: only the directory, the Nix store and three devices exist there (no `/etc`, `/home` or `/proc`), with no network and no capabilities. On top, [Landlock](https://landlock.io) lets it read only the directory and the tools' own files, write only when the server is started with `--writable`, and start only the allowed programs. It also gets CPU, address-space (4 GiB) and file-size limits and is killed after 5 minutes; the NixOS unit caps memory and processes for the service as a whole.
  12. Needs Linux 6.12 or newer (Landlock ABI 6) with unprivileged user namespaces; the server checks at startup and refuses to run otherwise. NixOS allows them by default; Ubuntu blocks them through AppArmor (`kernel.apparmor_restrict_unprivileged_userns`).
  13. ## Usage
  14. ```sh
  15. nix build github:dafrick/dirmcp # or: nix run github:dafrick/dirmcp -- …
  16. openssl rand -hex 32 > token && chmod 600 token
  17. ./result/bin/dirmcp --root ~/notes --token-file token --create-in Inbox
  18. ```
  19. | Flag | Default | |
  20. |---|---|---|
  21. | `--root DIR` | required | the directory to serve |
  22. | `--token-file FILE` | required | bearer token, ≥ 32 bytes, mode 0600 or 0400 |
  23. | `--listen ADDR` | `127.0.0.1:8090` | MCP endpoint is `http://ADDR/mcp` (Streamable HTTP) |
  24. | `--writable` | off | programs may change files |
  25. | `--create-in DIR` | none | enable `create` below `DIR` (repeatable) |
  26. | `--allowed-host NAME` | none | public name a proxy in front uses (Host header), e.g. `notes.example.ts.net` (repeatable). Other names are refused (DNS rebinding); localhost always works |
  27. | `--tools FILE` | set by the package | tools manifest: program → store path |
  28. Clients send `Authorization: Bearer <token>`. For a claude.ai custom connector, put the URL of a public HTTPS proxy in front of `/mcp` and the header under "Request headers". The binary must come from the Nix package: it pins every tool to a store path and never searches `PATH`.
  29. ## NixOS
  30. ```nix
  31. # flake.nix
  32. inputs.dirmcp.url = "github:dafrick/dirmcp/v0.3.0";
  33. # in the host's modules:
  34. imports = [ inputs.dirmcp.nixosModules.default ];
  35. services.dirmcp.instances.notes = {
  36. root = "/srv/notes";
  37. listen = "127.0.0.1:8090";
  38. tokenFile = "/run/secrets/dirmcp_notes_token"; # root-only, e.g. sops-nix
  39. createIn = [ "Inbox" ]; # read-only, plus new files in Inbox/
  40. allowedHosts = [ "box.example.ts.net" ]; # the proxy's public name
  41. # writable = true; # let programs change files
  42. # user = "…"; extraGroups = [ "…" ]; # to share access to the root
  43. };
  44. ```
  45. Each instance is `dirmcp-<name>.service`, running as its own system user (created unless you name an existing one). The unit reads the token as a systemd credential and is hardened: read-only system, no home directories, private `/tmp` and `/dev`, loopback-only networking when it listens on loopback (a warning otherwise), `MemoryMax` and `TasksMax` (options `memoryMax`, `tasksMax`). Home directories are hidden; the root is bound back, read-only unless `writable`, with the `createIn` folders writable. It keeps open only what the sandbox needs: user, mount and network namespaces, the `@mount` and `@sandbox` system calls, and `CAP_SYS_ADMIN` and `CAP_SETPCAP` in the bounding set. The service user has no capabilities on the host; those two only exist inside each program's own user namespace and are dropped before the program starts.
  46. ## Deploying securely
  47. **What you are giving away.** Whoever holds the token can read every file under the root, with all the power of grep, rg, find, awk and sed. With `--writable` they can also change, move and delete (to `.trash/`, but `mv`, `sed -i` and `>` overwrite for good). Treat the token like an SSH key to that directory.
  48. - **Serve as little as possible.** Point `--root` at the folder you mean, not its parent. Prefer read-only with `--create-in` for additions; use `--writable` only if you need edits, and keep backups or version history (e.g. Obsidian Sync) of the folder.
  49. - **Run as a user that can only reach that folder.** File permissions are the last line: a read-only instance should run as a user without write access to the root, so a bug in dirmcp cannot write either. The module creates its own user; give it access to the root through a group or ACLs. Never run it as root (the module refuses) or as your own account. New files are group-readable and group-writable (`UMask=0007`), so do not give the service a widely shared primary group.
  50. - **Keep it on loopback and put HTTPS in front.** dirmcp speaks plain HTTP. Expose only `/mcp` through a TLS reverse proxy or a tunnel (Tailscale Funnel, Cloudflare Tunnel), and list its public name with `--allowed-host` (other Host headers are refused). Never bind it to a public interface directly.
  51. - **Token.** 32 random bytes or more (`openssl rand -hex 32`), stored root-only (sops, agenix) and passed as a credential. Put it only into the client's connector settings (claude.ai: "Request headers", `Authorization: Bearer …`). Rotate it if it may have leaked: change the secret, restart the service, update the connector.
  52. - **Watch it.** Every call is logged: tool, the first 200 characters of the command, exit code, size (`journalctl -u dirmcp-<name>`). File contents are not logged, but a command can contain text (`echo … >`, here-docs), so treat the journal as sensitive. Failed tokens are logged with the remote address; behind a proxy or tunnel that is always the proxy (127.0.0.1).
  53. - **Switch it off** at once with `systemctl stop dirmcp-<name>` (or by removing the tunnel), then rotate the token.
  54. - **Check the host.** The server refuses to start without Landlock ABI 6 and unprivileged user namespaces; do not work around that.
  55. ## Layout
  56. ```
  57. AGENTS.md, CLAUDE.md agent instructions (CLAUDE.md imports AGENTS.md)
  58. SECURITY.md how to report a vulnerability
  59. CONTRIBUTING.md how to make changes
  60. VERSION, CHANGELOG.md version and changelog
  61. flake.nix dev shell, checks, package (with the tools manifest)
  62. cmd/dirmcp/ main: flags, startup checks, HTTP server
  63. nix/ NixOS module and its VM test
  64. internal/ argcheck (option allowlists), confine (Landlock helper),
  65. shell (interpreter), jobs (paging), create, server, manifest
  66. docs/adr/ architecture decision records
  67. openspec/ OpenSpec specs and changes
  68. scripts/ small helper scripts (release check)
  69. .github/ CI, Dependabot
  70. ```
  71. ## Getting started
  72. 1. Install Nix ([nixos.org/download](https://nixos.org/download)) and enable flakes.
  73. 2. Enter the dev shell: `nix develop`. It provides the tools (Go, `openspec`, `gh`) and installs the git hooks.
  74. 3. Run all checks:
  75. ```sh
  76. nix flake check # pre-commit hooks
  77. pre-commit run --all-files --hook-stage pre-push # pre-push hooks
  78. ```
  79. Then read [CONTRIBUTING.md](CONTRIBUTING.md).
  80. ## License
  81. MIT, see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.