filesystem-mcp

A production-ready MCP (Model Context Protocol) server that gives AI agents full control over a filesystem — reading, writing, editing, searching, diffing files, executing commands, and managing processes. Built in Go with OAuth authorization and RBAC.

Features

• 🗂️ 12 powerful tools for filesystem operations, shell execution, and agent utilities
• 🔐 RBAC with JWT + CEL — restrict operations per path using glob patterns and JWT claim expressions
• ⚡ Token-efficient by design — partial file reads, batch edits, ranged diffs, search with context control
• 🔑 OAuth RFC 8414 / RFC 9728 compliant — .well-known/oauth-protected-resource and .well-known/oauth-authorization-server
• 🛡️ JWT validation — validated locally via JWKS + CEL expressions
• 🚀 Dual transport — stdio for local clients, HTTP for remote (Claude Web, OpenAI, etc.)

Tools

Filesystem

Tool	Description
ls	List directory contents with depth, glob filter, hidden file toggle. depth=1 is flat, depth=N is tree
read_file	Read a file fully or specific line ranges. Accepts an array of {offset, limit} ranges for partial reads
write_file	Create or overwrite a file. Auto-creates parent directories. Saves undo state
edit_file	Batch find-and-replace on a file. Accepts an array of {old_text, new_text, replace_all} edits applied sequentially. Reports successes and failures
search	Recursive grep with regex or literal mode. Configurable include/exclude patterns, context lines, max results
diff	Unified diff between two files or sections. Supports line ranges on both sides

Shell & Processes

Tool	Description
exec	Execute shell commands in foreground (with timeout) or background (returns process ID)
process_status	Get output and status of a background process, or list all background processes
process_kill	Kill a background process

System & Utilities

Tool	Description
system_info	OS, architecture, hostname, user, working directory, shell, PATH
undo	Revert a file to its state before the last write_file or edit_file
scratch	In-memory key-value store for the agent to save/retrieve temporary data between calls

RBAC

RBAC controls which operations are allowed on which filesystem paths. Rules are evaluated in order — first match wins.

Operation Categories

Category	Tools	Notes
read	ls, read_file, search, diff	Safe, read-only operations
write	write_file, edit_file, undo	Modifies files
exec	exec, process_status, process_kill	Full shell access — granting this bypasses filesystem restrictions

system_info and scratch don't touch the filesystem and are always allowed.

Configuration

rbac:
  enabled: true
  default_policy: deny # deny | allow

  rules:
    - name: "admins"
      when:
        - 'payload.groups.exists(g, g == "admin")'
      paths: ["/**"]
      operations: [read, write, exec]

    - name: "developers"
      when:
        - 'payload.groups.exists(g, g == "developer")'
      paths: ["/home/*/projects/**", "/tmp/**"]
      operations: [read, write]

    - name: "viewers"
      when:
        - 'payload.scope.contains("read")'
      paths: ["/home/*/projects/**"]
      operations: [read]

    - name: "anonymous - no JWT"
      when: []
      paths: ["/tmp/sandbox/**"]
      operations: [read]

• when — CEL expressions evaluated against the JWT payload. All must be true (AND). Empty or missing matches requests without JWT
• paths — Glob patterns. /** suffix matches everything recursively
• operations — read, write, exec
• default_policy — deny (secure by default) or allow (open, for development)

⚠️ Warning: Granting exec gives the agent full shell access. Any filesystem restrictions from paths can be bypassed via shell commands. Only grant exec to trusted identities.

Installation

From source

Requires Go 1.24+.

git clone https://github.com/achetronic/filesystem-mcp.git
cd filesystem-mcp
make build

Output: bin/filesystem-mcp-{os}-{arch}

From release binaries

Download a prebuilt binary from the Releases page. Binaries are available for linux/{386,amd64,arm64} and darwin/{amd64,arm64}.

Why no Docker image?

This MCP server is designed to control the host filesystem — reading, writing, editing files, and executing shell commands. Running it inside a container would defeat its purpose: the agent would only see the container's filesystem, not yours. Bind-mounting the entire host filesystem into a container introduces complexity and security pitfalls that are worse than just running the binary directly.

If you need network-accessible deployment (HTTP transport), run the binary as a systemd service or behind a reverse proxy. The Dockerfile and Helm chart are kept in the repo for edge cases where containerized deployment makes sense (e.g., sandboxed CI environments with specific volume mounts), but they are not the recommended way to run this.

Running

Run locally

make run

Default config starts an HTTP server on :8080. For stdio mode, modify the Makefile to use docs/config-stdio.yaml.

Client Configuration

Stdio Mode (Claude Desktop, Cursor, VSCode)

make build

// claude_desktop_config.json
{
  mcpServers: {
    filesystem: {
      command: "/path/to/bin/filesystem-mcp-linux-amd64",
      args: ["--config", "/path/to/docs/config-stdio.yaml"],
    },
  },
}

HTTP Mode (Remote clients)

npm i mcp-remote && make run

// claude_desktop_config.json
{
  mcpServers: {
    "filesystem-remote": {
      command: "npx",
      args: [
        "mcp-remote",
        "http://localhost:8080/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization: Bearer ${JWT}",
      ],
      env: {
        JWT: "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
      },
    },
  },
}

Configuration

Configuration is YAML-based, loaded via --config flag. Supports environment variable expansion ($VAR / ${VAR}).

See example configs:

• HTTP mode — Full config with JWT, RBAC, OAuth endpoints
• Stdio mode — Minimal config for local use

Documentation

• MCP Authorization Requirements
• RFC 9728 — OAuth Protected Resource Metadata
• MCP Go Library
• mcp-remote package
• CEL Specification

Contributing

All contributions are welcome!

• Open an issue to report bugs or request features
• Submit a pull request to contribute improvements

License

Licensed under the Apache 2.0 License.